API Document

Basic graph pattern

add_fact

add_fact(self, s, p, o, p_prefix)

Add a <s, p, o, prefix> triple to the query.

Parameters:

• s(str): the subject of the triple

• p(str): the predicate of the triple

• o(str): the object of the triple

• p_prefix(str): the prefix of predicate

example:

• Question:

What is the manufacturer of 2T Stalker

• Program:

a=PyQL()
a.add_fact('Q222823', 'P176', 'x0' ,'wdt')

• SPARQL:

SELECT DISTINCT * {
	wd:Q222823 wdt:P176 ?x0.
}

add_quantity

add_quantity(entity, prop, tag,time=False)

This function is used to acquire the value of a quantity property.

Parameters:

• entity(str): the entity

• prop(str): the quantity property you need to get

• tag(str): An identifier used to name variables. Ultimately the variable with the property value of this quantity property is the tag.

• time(int/boolean/str): The constraint of time.

  • int: Limit the time to this year.

  • boolean: True means need to acquire the time，False means not need to acquire the time.

  • str: use the function to_date to set the entire yyyy-mm-dd

example:

• Question:

What is the GDP of French economy in the year 2007

• Program:

a=PyQL()
a.add_quantity('Q8057','P4010','x0',2007)

• SPARQL:

SELECT DISTINCT ?x0 {
	wd:Q8057 p:P4010 ?statement_x0.
	?statement_x0 psv:P4010 ?value_st_x0.
	?value_st_x0 wikibase:quantityAmount ?x0.
	?statement_x0 pq:P585 ?time_x0.
	FILTER(YEAR(?time_x0) = 2007).
}

add_quantity_by_qualifier

add_quantity_by_qualifier(self,entity,main_prop,main_obj,qualifier_prop,tag)

Acquire the value of a quantity property which acts as a qualifier.

For example, the entity iPhone 12 has a property 'made from material' of which the value can be steel, glass and so on. The property mass is the qualifier for each material.

Parameters:

• entity(str): the entity, such as iPhone12

• main_prop(str): the property of the statement, such as made from material

• main_obj(str): the value of the main_prop, such as steel.

• qualifier_prop(str): the quantity property which acts as a qualifier. For example, mass.

• tag(str): An identifier used to name variables. Ultimately the variable with the property value of this quantity property is the tag.

example:

• Question:

What is the duration of Soyuz MS-21's time on the moon

• Program:

a=PyQL()
a.add_quantity_by_qualifier('Q100375849','P793','x1','P2047','x0')

• SPARQL:

SELECT DISTINCT ?x0 {
	wd:Q100375849 p:P793 ?statement_x0.
	?statement_x0 ps:P793 ?x1.
	?statement_x0 pqv:P2047 ?value_st_x0.
	?value_st_x0 wikibase:quantityAmount ?x0.
}

add_quantity_with_qualifier

add_quantity_with_qualifier(self,entity,main_prop,qualifier_prop,qualifier_obj,tag)

Acquire the value of a quantity property with a qualifire limiting other peoperties

For example, the computer performance of Nvidia GeForce RTX 3090 has 4 statements which are limited by the qualifier uses. Their qualifier values are single-precision floating-point format, half-precision floating-point format, double-precision floating-point format and half-precision floating-point format seperately.

Parameters:

• entity(str): the entity, such as Nvidia GeForce RTX 3090

• main_prop(str): the quantity property of the statement, such as computer performance

• qualifier_prop(str): the property which acts as a qualifier, such as uses

• qualifier_obj(str): the value of qualifier property, such as single-precision floating-point format.

• tag(str): An identifier used to name variables. Ultimately the variable with the property value of this quantity property is the tag.

example:

• Question:

What is the solubility of Dihydrogen disulfide in water

• Program:

a=PyQL()
a.add_quantity_with_qualifier('Q170591','P2177','P2178','Q283','x0')

• SPARQL:

SELECT DISTINCT ?x0 {
	wd:Q170591 p:P2177 ?statement_x0.
	?statement_x0 psv:P2177 ?value_st_x0.
	?value_st_x0 wikibase:quantityAmount ?x0.
	?statement_x0 pq:P2178 wd:Q283.
}

add_type_constrain

add_type_constrain(self, type_id, new_var)

add a type constraint to a variable

Parameters:

• type_id(str): ID of the type

• new_var(str): the entity to be constrained

example:

• Question: Get all the Pan Am Games.

• Program:

a=PyQL()
a.add_type_constrain('Q230186','x0')
a.set_answer("x0")

• SPARQL:

SELECT DISTINCT ?x0 {
	?x0 wdt:P31/wdt:P279* wd:Q230186.
}

add_filter

add_filter(self, compare_obj1, operator, compare_obj2)

Given two comarison variables and an operator, add a filter.

Parameters:

• compare_obj1(str): comparison variable 1

• operator(str): operator

• compare_obj2(str): comparison variable 2

example:

• Question:

Get all the Pan Am Games held after 2001 (not including 2001).

• Program:

a=PyQL()
a.add_type_constrain('Q230186', 'x0')
a.add_time('x0', 'x1')
a.add_filter(year('x1'), '>', 2001)
a.set_answer("x0")

• SPARQL:

SELECT DISTINCT ?x0 {
	?x0 wdt:P31/wdt:P279* wd:Q230186.
	
	?x0 wdt:P585 ?x1.
	
	FILTER(YEAR(?x1) > 2001).
}

add_bind

add_bind(self, equation, var_name)

add a bind expression to assign the result of the expression equation to the variable var_name.

Parameters:

• equation(str): The expression to be binded. Bracket is not necessary. It will be added automatically.

• var_name(str): The expression will be assigned to this variable.

example:

• Question:

What is the number of deaths and injuried individuals in Atlanta spa shootings?

• Program:

a=PyQL()
a.add_quantity('Q105982031','P1120','x0')
a.add_quantity('Q105982031','P1339','x1')
a.add_bind(add('x0', 'x1'), 'x2')

• SPARQL:

SELECT DISTINCT ?x2 {
	wd:Q105982031 p:P1120 ?statement_x0.
	?statement_x0 psv:P1120 ?value_st_x0.
	?value_st_x0 wikibase:quantityAmount ?x0.
	
	wd:Q105982031 p:P1339 ?statement_x1.
	?statement_x1 psv:P1339 ?value_st_x1.
	?value_st_x1 wikibase:quantityAmount ?x1.
	
	BIND( ((?x0 + ?x1)) AS ?x2 )
}

add_assignment

add_assignment(self,var_list,new_var)

add a values clause to generate a new variable new var of which the value includes all entities in var_list.

Parameters:

• equation(list): an entities list, such as ['Q123', 'Q186']

• new_var(str): the new variable

example:

• Question:

Among BMW N57 and Renault E-Type engine, who has the highest compression ratio?

• Program:

a=PyQL()
a.add_assignment(['Q796629','Q3866356'],'x2')
a.add_quantity('x2','P1247','x0')
a.add_max('x0','x2')

• SPARQL:

SELECT DISTINCT ?x2 {
	Values ?x2 {wd:Q796629 wd:Q3866356}
	?x2 p:P1247 ?statement_x0.
	?statement_x0 psv:P1247 ?value_st_x0.
	?value_st_x0 wikibase:quantityAmount ?x0.
}
ORDER BY DESC(?x0)
LIMIT 1

add_sub_query

add_sub_query(self,*sub_query)

add a sub query to the sparql of this PyQL instance

Parameters:

• sub_query(PyQL): the PyQL instance which needs to be added as a sub_query

example:

• Question:

By how much is the average lowest air pressure of a category 5 hurricane lower than that of a category 3 hurricane?

• Program:

a = PyQL()
a.add_quantity('x4', 'P2532', 'x2')
a.add_fact('x4', 'P31', 'Q63100611', 'wdt')
a.add_avg('x2', 'x1')
b = PyQL()
b.add_quantity('x5', 'P2532', 'x3')
b.add_fact('x5', 'P31', 'Q63100595', 'wdt')
b.add_avg('x3', 'x0')
c = PyQL()
c.add_bind(sub('x0', 'x1'), 'x6')
c.add_sub_query(a, b)

• SPARQL:

SELECT DISTINCT ?x6 {
	{
		SELECT (AVG(?x2) AS ?x1 )  {
			?x4 p:P2532 ?statement_x2.
			?statement_x2 psv:P2532 ?value_st_x2.
			?value_st_x2 wikibase:quantityAmount ?x2.
			
			?x4 wdt:P31 wd:Q63100611.
		}
		
	}
	{
		SELECT (AVG(?x3) AS ?x0 )  {
			?x5 p:P2532 ?statement_x3.
			?statement_x3 psv:P2532 ?value_st_x3.
			?value_st_x3 wikibase:quantityAmount ?x3.
			
			?x5 wdt:P31 wd:Q63100595.
		}
		
	}
	BIND( ((?x0 - ?x1)) AS ?x6 )
}

Aggreggation

add_max

add_max(self, max_obj, return_obj='*',offset=0,limit=1)

Calculate the maximum value of max_obj

Parameters:

• max_obj(str): the variable of which the maximum value needs to be counted

• return_obj(str): the variable to return. It can be *

• offset(str): the number in offset. For example, to get the second biggest one, set offset=2

• limit(str): the number in limit. For example, to get the three biggest one, set limit=3, offset=0

example:

• Question:

Among BMW N57 and Renault E-Type engine, who has the highest compression ratio?

• Program:

a=PyQL()
a.add_assignment(['Q796629','Q3866356'],'x2')
a.add_quantity('x2','P1247','x0')
a.add_max('x0','x2')

• SPARQL:

SELECT DISTINCT ?x2 {
	Values ?x2 {wd:Q796629 wd:Q3866356}
	?x2 p:P1247 ?statement_x0.
	?statement_x0 psv:P1247 ?value_st_x0.
	?value_st_x0 wikibase:quantityAmount ?x0.
}
ORDER BY DESC(?x0)
LIMIT 1

add_min

add_min(self, min_obj, return_obj='*',offset=0,limit=1)

Calculate the minimum value of min_obj

Parameters:

• max_obj(str): the variable of which the minimum value needs to be counted

• return_obj(str): the variable to return. It can be *

• offset(str): the number in offset. For example, to get the second smallest one, set offset=2

• limit(str): the number in limit. For example, to get the three smallest one, set limit=3, offset=0

example:

• Question: Among BMW N57 and Renault E-Type engine, who has the lowest compression ratio?

• Program:

a=PyQL()
a.add_assignment(['Q796629','Q3866356'],'x2')
a.add_quantity('x2','P1247','x0')
a.add_min('x0','x2')

• SPARQL:

SELECT DISTINCT ?x2 {
	Values ?x2 {wd:Q796629 wd:Q3866356}
	?x2 p:P1247 ?statement_x0.
	?statement_x0 psv:P1247 ?value_st_x0.
	?value_st_x0 wikibase:quantityAmount ?x0.
}
ORDER BY (?x0)
LIMIT 1

add_avg

add_avg(self,avg_var, new_var, group_obj=None)

calculate the average value of variable avg_var. The parameter new_var is the variable of the calculated average value.

Parameters:

• avg_var(str): the variable which needs to be averaged

• new_var(str): the variable of the calculated average value

• group_obj(str): the variable which needs to be put in a group by

example:

• Question:

Among BMW N57 and Renault E-Type engine, what is the average compression ratio?

• Program:

a=PyQL()
a.add_assignment(['Q796629','Q3866356'],'x2')
a.add_quantity('x2','P1247','x0')
a.add_avg('x0','x1')

• SPARQL:

SELECT (AVG(?x0) AS ?x1 )  {
	Values ?x2 {wd:Q796629 wd:Q3866356}
	?x2 p:P1247 ?statement_x0.
	?statement_x0 psv:P1247 ?value_st_x0.
	?value_st_x0 wikibase:quantityAmount ?x0.
}

add_sum

add_sum(self,sum_var, new_var, group_obj=None)

calculate the sum of the variable sum_var. The parameter new_var is the variable of the calculated sum value.

Parameters:

• sum_var(str): the variable which needs to be summed

• new_var(str): the variable of the calculated sum value

• group_obj(str): the variable which needs to be put in a group by

example:

• Question:

What are the female population of all the communes of France in 2017?

• Program:

a=PyQL()
a.add_type_constrain('Q484170','x0')
a.add_quantity('x0','P1539','x1',2017)
a.add_sum("x1","x2")

• SPARQL:

SELECT (SUM(?x1) AS ?x2 )  {
	?x0 wdt:P31/wdt:P279* wd:Q484170.
	
	?x0 p:P1539 ?statement_x1.
	?statement_x1 psv:P1539 ?value_st_x1.
	?value_st_x1 wikibase:quantityAmount ?x1.
	?statement_x1 pq:P585 ?time_x1.
	FILTER(YEAR(?time_x1) = 2017).
	
}

add_count

add_count(self,count_obj,new_var, group_obj=None)

calculate the average value of variable count_obj. The parameter new_var is the variable of the calculated average value. It can only be used in the final step of a complete query or subquery. After use, either the entire query ends or it is treated as a subquery.

Parameters:

• count_obj(str): the variable which needs to be counted

• new_var(str): the variable of the calculated counting value

• group_obj(str): the variable which needs to be put in a group by

example:

• Question:

What is the number of all the communes of France?

• Program:

a=PyQL()
a.add_type_constrain('Q484170','x0')
a.add_count("x0","x1")

• SPARQL:

SELECT (COUNT(DISTINCT ?x0) AS ?x1)  {
	?x0 wdt:P31/wdt:P279* wd:Q484170.
}

add_rank

add_rank(self, rank_var, var_list,new_var)

calculate the rank of rank_var's value among var_list

Parameters:

• rank_var(str): the variable of which the rank needs to be calculated

• var_list(str): the rank is calculated in this list which includes rank_var

• new_var(str): the variable of the rank result

example:

• Question:

What is Italy's population ranking among all the sovereign states in 2020?

• Program:

a=PyQL()
a.add_type_constrain('Q3624078','x0')
a.add_quantity("x0", "P1082", "x1", 2020)
a.add_quantity("Q38","P1082","x2",2020)
a.add_rank("x2","x1","x3")

• SPARQL:

SELECT (COUNT(DISTINCT ?x1) +1 AS ?x3) {
	?x0 wdt:P31/wdt:P279* wd:Q3624078.
	
	?x0 p:P1082 ?statement_x1.
	?statement_x1 psv:P1082 ?value_st_x1.
	?value_st_x1 wikibase:quantityAmount ?x1.
	?statement_x1 pq:P585 ?time_x1.
	FILTER(YEAR(?time_x1) = 2020).
	
	
	wd:Q38 p:P1082 ?statement_x2.
	?statement_x2 psv:P1082 ?value_st_x2.
	?value_st_x2 wikibase:quantityAmount ?x2.
	?statement_x2 pq:P585 ?time_x2.
	FILTER(YEAR(?time_x2) = 2020).
	
	
	FILTER(?x2 < ?x1).
}

Boolean

add_compare

add_compare(self, obj1, op, obj2)

Determine whether obj1 and obj2 satisfies the size relationship represented by op. It can only be used in the final step of a complete query.

Parameters:

• obj1(str): comparison variable 1

• op(str): operator

• obj2(str): comparison variable 2

example:

• Question:

Is Italy's population more than France's population in 2020?

• Program:

a = PyQL()
a.add_quantity("Q142", "P1082", "x1", 2020)
a.add_quantity("Q38", "P1082", "x2", 2020)
a.add_compare("x2",">","x1")

• SPARQL:

SELECT ?answer {
	wd:Q142 p:P1082 ?statement_x1.
	?statement_x1 psv:P1082 ?value_st_x1.
	?value_st_x1 wikibase:quantityAmount ?x1.
	?statement_x1 pq:P585 ?time_x1.
	FILTER(YEAR(?time_x1) = 2020).
	
	
	wd:Q38 p:P1082 ?statement_x2.
	?statement_x2 psv:P1082 ?value_st_x2.
	?value_st_x2 wikibase:quantityAmount ?x2.
	?statement_x2 pq:P585 ?time_x2.
	FILTER(YEAR(?time_x2) = 2020).
	
	
	BIND( (IF(?x2 > ?x1, "TRUE", "FALSE")) AS ?answer )
}

Other

add_time

add_time(self, entity, new_var)

Get the point of time property of entity. It adds a triple <entity, wdt:P585, new_var>

Parameters:

• entity(str): The entity whose point of time is needed.

• new_var(str): The variable which represents the point of time value of the entity

example:

• Question:

Get all the Pan Am Games held after 2001 (not including 2001).

• Program:

a=PyQL()
a.add_type_constrain('Q230186', 'x0')
a.add_time('x0', 'x1')
a.add_filter(year('x1'), '>', 2001)
a.set_answer("x0")

• SPARQL:

SELECT DISTINCT ?x0 {
	?x0 wdt:P31/wdt:P279* wd:Q230186.
	
	?x0 wdt:P585 ?x1.
	
	FILTER(YEAR(?x1) > 2001).
}

add_start_time

add_start_time(self, entity,new_var)

Get the start time property of entity. It adds a triple <entity, wdt:P580, new_var>

Parameters:

• entity(str): The entity whose start time is needed.

• new_var(str): The variable which represents the start time value of the entity

example:

• Question:

What is the start time of Efficacy and Safety Study of Mongersen (GED-0301) for the Treatment of Subjects With Active Crohn's Disease?

• Program:

a = PyQL()
a.add_start_time('Q64216670', 'x0')
a.set_answer('x0')

• SPARQL:

SELECT DISTINCT ?x0 {
	wd:Q64216670 wdt:P580 ?x0.
}

add_end_time

add_end_time(self, entity, new_var)

Get the end time property of entity. It adds a triple <entity, wdt:P582, new_var>

Parameters:

• entity(str): The entity whose end time is needed.

• new_var(str): The variable which represents the end time value of the entity

example:

• Question:

What is the start time of Efficacy and Safety Study of Mongersen (GED-0301) for the Treatment of Subjects With Active Crohn's Disease?

• Program:

a = PyQL()
a.add_end_time('Q64216670', 'x0')
a.set_answer('x0')

• SPARQL:

SELECT DISTINCT ?x0 {
	wd:Q64216670 wdt:P582 ?x0.
}

set_answer

set_answer(self,answer='*')

Set the return value of the final query. It can only be used at last.

Parameters:

• answer(str): The return value of this query.

example:

• Question:

What is the start time of Efficacy and Safety Study of Mongersen (GED-0301) for the Treatment of Subjects With Active Crohn's Disease?

• Program:

a = PyQL()
a.add_end_time('Q64216670', 'x0')
a.set_answer('x0')

• SPARQL:

SELECT DISTINCT ?x0 {
	wd:Q64216670 wdt:P582 ?x0.
}

Arithmetic

These functions are used inside an add_bind. They are not member functions of PyQL class.

add

add(*para_list)

It creates an addition expression which adds up every element in para_list.

example:

• Question:

What is the number of deaths and injuried individuals in Atlanta spa shootings?

• Program:

a=PyQL()
a.add_quantity('Q105982031','P1120','x0')
a.add_quantity('Q105982031','P1339','x1')
a.add_bind(add('x0', 'x1'), 'x2')

• SPARQL:

SELECT DISTINCT ?x2 {
	wd:Q105982031 p:P1120 ?statement_x0.
	?statement_x0 psv:P1120 ?value_st_x0.
	?value_st_x0 wikibase:quantityAmount ?x0.
	
	wd:Q105982031 p:P1339 ?statement_x1.
	?statement_x1 psv:P1339 ?value_st_x1.
	?value_st_x1 wikibase:quantityAmount ?x1.
	
	BIND( ((?x0 + ?x1)) AS ?x2 )
}

sub

sub(para1, para2)

It creates an subtraction expression of para1 subtacting para2.

example:

• Question:

How much more is France's population than Italy's population in 2020?

• Program:

a = PyQL()
a.add_quantity("Q142", "P1082", "x1", 2020)
a.add_quantity("Q38", "P1082", "x2", 2020)
a.add_bind(sub('x1','x2'),'x3')

• SPARQL:

SELECT DISTINCT ?x3 {
	wd:Q142 p:P1082 ?statement_x1.
	?statement_x1 psv:P1082 ?value_st_x1.
	?value_st_x1 wikibase:quantityAmount ?x1.
	?statement_x1 pq:P585 ?time_x1.
	FILTER(YEAR(?time_x1) = 2020).
	
	
	wd:Q38 p:P1082 ?statement_x2.
	?statement_x2 psv:P1082 ?value_st_x2.
	?value_st_x2 wikibase:quantityAmount ?x2.
	?statement_x2 pq:P585 ?time_x2.
	FILTER(YEAR(?time_x2) = 2020).
	
	
	BIND( ((?x1 - ?x2)) AS ?x3 )
}

mul

mul(*para_list)

It creates an multiplication expression which multiplies every element in para_list.

example:

• Question:

What is a half of the population of France in 2020?

• Program:

a = PyQL()
a.add_quantity("Q142", "P1082", "x1", 2020)
a.add_bind(mul('x1', 0.5), 'x2')

• SPARQL:

SELECT DISTINCT ?x2 {
	wd:Q142 p:P1082 ?statement_x1.
	?statement_x1 psv:P1082 ?value_st_x1.
	?value_st_x1 wikibase:quantityAmount ?x1.
	?statement_x1 pq:P585 ?time_x1.
	FILTER(YEAR(?time_x1) = 2020).
	
	
	BIND( (?x1 * 0.5) AS ?x2 )
}

div

div(para1, para2)

It creates an division expression of para1 dividing para2.

example:

• Question:

How many times the population of France is that of Italy in 2020?

• Program:

a = PyQL()
a.add_quantity("Q142", "P1082", "x1", 2020)
a.add_quantity("Q38", "P1082", "x2", 2020)
a.add_bind(div('x1','x2'),'x3')

• SPARQL:

SELECT DISTINCT ?x3 {
	wd:Q142 p:P1082 ?statement_x1.
	?statement_x1 psv:P1082 ?value_st_x1.
	?value_st_x1 wikibase:quantityAmount ?x1.
	?statement_x1 pq:P585 ?time_x1.
	FILTER(YEAR(?time_x1) = 2020).
	
	
	wd:Q38 p:P1082 ?statement_x2.
	?statement_x2 psv:P1082 ?value_st_x2.
	?value_st_x2 wikibase:quantityAmount ?x2.
	?statement_x2 pq:P585 ?time_x2.
	FILTER(YEAR(?time_x2) = 2020).
	
	
	BIND( (?x1 / ?x2) AS ?x3 )
}

abs

abs(para)

It creates an expression which is abs(para)

example:

• Question:

What is the difference between Italy's population and France's population in 2020?

• Program:

a = PyQL()
a.add_quantity("Q142", "P1082", "x1", 2020)
a.add_quantity("Q38", "P1082", "x2", 2020)
a.add_bind(sub('x2', 'x1'), 'x3')
a.add_bind(abs('x3'),'x4')

• SPARQL:

SELECT DISTINCT ?x4 {
	wd:Q142 p:P1082 ?statement_x1.
	?statement_x1 psv:P1082 ?value_st_x1.
	?value_st_x1 wikibase:quantityAmount ?x1.
	?statement_x1 pq:P585 ?time_x1.
	FILTER(YEAR(?time_x1) = 2020).
	
	
	wd:Q38 p:P1082 ?statement_x2.
	?statement_x2 psv:P1082 ?value_st_x2.
	?value_st_x2 wikibase:quantityAmount ?x2.
	?statement_x2 pq:P585 ?time_x2.
	FILTER(YEAR(?time_x2) = 2020).
	
	
	BIND( ((?x2 - ?x1)) AS ?x3 )
	
	BIND( (ABS(?x3)) AS ?x4 )
}