Query the Data Commons Knowledge Graph using SPARQL
datacommons.query(query_string, select=None)
Returns the results of running a graph query on the Data Commons knowledge graph using SPARQL.
Arguments
-
sparql (str)
: A SPARQL query string. -
select
(func
accepting a row in the query result) - A function that selects rows to be returned byquery
. This function accepts a row in the results of executingquery_string
and return True if and only if the row is to be returned byquery
. The row passed in as an argument is represented as adict
that maps a query variable inquery_string
to its value in the given row.
This API only supports a subset of SPARQL keywords including:
- ORDER BY
- DISTINCT
- LIMIT
In the query, each variable should have a typeOf
condition, e.g. "?var typeOf
City ."
.
Returns
A table, represented as a list
of rows, resulting from executing the given
SPARQL query. Each row is a dict
mapping query variable to its value in the
row. If select
is not None
, then a row is included in the returned list
if and only if select
returns True
for that row.
Raises
ValueError
- If the payload returned by the Data Commons REST API is malformed.
Examples
Examples
We would like to query for the name associated with three states identified by their DCIDs California, Kentucky, and Maryland.
>>> import datacommons as dc
>>> dc.set_api_key(YOUR_API_KEY_HERE)
>>> query_str = '''
... SELECT ?name ?dcid
... WHERE {
... ?a typeOf Place .
... ?a name ?name .
... ?a dcid ("geoId/06" "geoId/21" "geoId/24") .
... ?a dcid ?dcid
... }
... '''
>>> result = dc.query(query_str)
>>> for r in result:
... print(r)
{"?name": "Maryland", "?dcid": "geoId/24"}
{"?name": "Kentucky", "?dcid": "geoId/21"}
{"?name": "California", "?dcid": "geoId/06"}
Optionally, we can specify which rows are returned by setting select
like so. The following returns all rows where the name is “Maryland”:
>>> selector = lambda row: row['?name'] == 'Maryland'
>>> result = dc.query(query_str, select=selector)
>>> for r in result:
... print(r)
{"?name": "Maryland", "?dcid": "geoId/24"}