Skip to content

Add independent filters, optional destinations and python_values to queries #77

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
srmnitc wants to merge 6 commits into
base: audit-fixes
Choose a base branch
from
Open

Add independent filters, optional destinations and python_values to queries #77

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
6356da4
Allow several independent filter conditions in one query
srmnitc Sep 27, 2026
7b5648b
Add optional destinations with term.optional
srmnitc Sep 27, 2026
5cb87db
Fix stepped queries whose intermediate step is an object property
srmnitc Sep 27, 2026
1223135
Add python_values option to query()
srmnitc Sep 27, 2026
2fd4b9a
Indent OPTIONAL blocks consistently
srmnitc Sep 27, 2026
769b444
Document independent conditions, optional properties and python_values
srmnitc Sep 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
349 changes: 349 additions & 0 deletions examples/02_advanced_query_building.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -860,6 +860,352 @@
"These selectors become particularly useful when combined with comparison operators and filters."
]
},
{
"cell_type": "markdown",
"id": "8b8991f1",
"metadata": {},
"source": [
"## Several Independent Conditions\n",
"\n",
"Instead of combining conditions with `&`, you can pass them as separate destinations. Each condition becomes its own `FILTER`, and all of them must hold. This also makes range queries on a single property easy to write:"
]
},
{
"cell_type": "code",
"execution_count": 13,
"id": "038a63b0",
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
"<div>\n",
"<style scoped>\n",
" .dataframe tbody tr th:only-of-type {\n",
" vertical-align: middle;\n",
" }\n",
"\n",
" .dataframe tbody tr th {\n",
" vertical-align: top;\n",
" }\n",
"\n",
" .dataframe thead th {\n",
" text-align: right;\n",
" }\n",
"</style>\n",
"<table border=\"1\" class=\"dataframe\">\n",
" <thead>\n",
" <tr style=\"text-align: right;\">\n",
" <th></th>\n",
" <th>Pizza</th>\n",
" <th>hasPricevalue</th>\n",
" <th>hasCalorificContentValuevalue</th>\n",
" </tr>\n",
" </thead>\n",
" <tbody>\n",
" <tr>\n",
" <th>0</th>\n",
" <td>American:245aa2f1</td>\n",
" <td>10.0</td>\n",
" <td>1292.0</td>\n",
" </tr>\n",
" </tbody>\n",
"</table>\n",
"</div>"
],
"text/plain": [
" Pizza hasPricevalue hasCalorificContentValuevalue\n",
"0 American:245aa2f1 10.0 1292.0"
]
},
"execution_count": 13,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"q = onto.query(g, onto.terms.pizza.Pizza,\n",
" [onto.terms.pizza.hasPrice >= 10,\n",
" onto.terms.pizza.hasPrice <= 11,\n",
" onto.terms.pizza.hasCalorificContentValue > 1000])\n",
"q"
]
},
{
"cell_type": "markdown",
"id": "09f99440",
"metadata": {},
"source": [
"## Optional Properties\n",
"\n",
"By default, every destination is required: an item missing any of the requested properties does not appear in the results. Use `.optional` to keep such items; the missing value is then empty. Only some pizzas in the knowledge graph have a spiciness:"
]
},
{
"cell_type": "code",
"execution_count": 14,
"id": "95c12455",
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
"<div>\n",
"<style scoped>\n",
" .dataframe tbody tr th:only-of-type {\n",
" vertical-align: middle;\n",
" }\n",
"\n",
" .dataframe tbody tr th {\n",
" vertical-align: top;\n",
" }\n",
"\n",
" .dataframe thead th {\n",
" text-align: right;\n",
" }\n",
"</style>\n",
"<table border=\"1\" class=\"dataframe\">\n",
" <thead>\n",
" <tr style=\"text-align: right;\">\n",
" <th></th>\n",
" <th>Pizza</th>\n",
" <th>hasPricevalue</th>\n",
" <th>hasSpiciness</th>\n",
" </tr>\n",
" </thead>\n",
" <tbody>\n",
" <tr>\n",
" <th>0</th>\n",
" <td>American:245aa2f1</td>\n",
" <td>10.0</td>\n",
" <td>None</td>\n",
" </tr>\n",
" <tr>\n",
" <th>1</th>\n",
" <td>AmericanHot:81efd537</td>\n",
" <td>11.5</td>\n",
" <td>Hot:3ba60921</td>\n",
" </tr>\n",
" <tr>\n",
" <th>2</th>\n",
" <td>Pizza:bec7e5f2</td>\n",
" <td>11.5</td>\n",
" <td>None</td>\n",
" </tr>\n",
" <tr>\n",
" <th>3</th>\n",
" <td>Margherita:3cfeae45</td>\n",
" <td>8.99</td>\n",
" <td>None</td>\n",
" </tr>\n",
" <tr>\n",
" <th>4</th>\n",
" <td>Margherita:e424656a</td>\n",
" <td>9.5</td>\n",
" <td>None</td>\n",
" </tr>\n",
" <tr>\n",
" <th>5</th>\n",
" <td>Mushroom:b6b736c9</td>\n",
" <td>11.0</td>\n",
" <td>None</td>\n",
" </tr>\n",
" <tr>\n",
" <th>6</th>\n",
" <td>Pizza:71307a5a</td>\n",
" <td>11.0</td>\n",
" <td>Hot:3ba60921</td>\n",
" </tr>\n",
" <tr>\n",
" <th>7</th>\n",
" <td>Pizza:f9f81adc</td>\n",
" <td>12.99</td>\n",
" <td>Mild:0bf38aee</td>\n",
" </tr>\n",
" </tbody>\n",
"</table>\n",
"</div>"
],
"text/plain": [
" Pizza hasPricevalue hasSpiciness\n",
"0 American:245aa2f1 10.0 None\n",
"1 AmericanHot:81efd537 11.5 Hot:3ba60921\n",
"2 Pizza:bec7e5f2 11.5 None\n",
"3 Margherita:3cfeae45 8.99 None\n",
"4 Margherita:e424656a 9.5 None\n",
"5 Mushroom:b6b736c9 11.0 None\n",
"6 Pizza:71307a5a 11.0 Hot:3ba60921\n",
"7 Pizza:f9f81adc 12.99 Mild:0bf38aee"
]
},
"execution_count": 14,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"q = onto.query(g, onto.terms.pizza.Pizza,\n",
" [onto.terms.pizza.hasPrice,\n",
" onto.terms.pizza.hasSpiciness.optional])\n",
"q"
]
},
{
"cell_type": "markdown",
"id": "b52ed58f",
"metadata": {},
"source": [
"A condition on an optional property only applies to that property: items that do not satisfy it are kept, with an empty value. In the generated query, the path, type and condition of the optional property are placed in their own `OPTIONAL` block:"
]
},
{
"cell_type": "code",
"execution_count": 15,
"id": "3a3b4a1f",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
" OPTIONAL {\n",
" ?Pizza pizza:hasCalorificContentValue ?hasCalorificContentValuevalue .\n",
" FILTER (?hasCalorificContentValuevalue>\"1300\"^^xsd:float)\n",
" }\n",
"}\n"
]
}
],
"source": [
"query = onto.create_query(onto.terms.pizza.Pizza,\n",
" [onto.terms.pizza.hasPrice,\n",
" (onto.terms.pizza.hasCalorificContentValue > 1300).optional])\n",
"print(query[query.index(\" OPTIONAL\"):])"
]
},
{
"cell_type": "markdown",
"id": "0374b411",
"metadata": {},
"source": [
"## Python Values\n",
"\n",
"Query results contain `rdflib` terms by default. With `python_values=True`, literals are converted to Python values and IRIs to strings, so numeric columns can be used directly for sorting, statistics or plotting:"
]
},
{
"cell_type": "code",
"execution_count": 16,
"id": "240ec56f",
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
"<div>\n",
"<style scoped>\n",
" .dataframe tbody tr th:only-of-type {\n",
" vertical-align: middle;\n",
" }\n",
"\n",
" .dataframe tbody tr th {\n",
" vertical-align: top;\n",
" }\n",
"\n",
" .dataframe thead th {\n",
" text-align: right;\n",
" }\n",
"</style>\n",
"<table border=\"1\" class=\"dataframe\">\n",
" <thead>\n",
" <tr style=\"text-align: right;\">\n",
" <th></th>\n",
" <th>Pizza</th>\n",
" <th>hasPricevalue</th>\n",
" <th>hasCalorificContentValuevalue</th>\n",
" </tr>\n",
" </thead>\n",
" <tbody>\n",
" <tr>\n",
" <th>2</th>\n",
" <td>Margherita:3cfeae45</td>\n",
" <td>8.99</td>\n",
" <td>848.0</td>\n",
" </tr>\n",
" <tr>\n",
" <th>3</th>\n",
" <td>Margherita:e424656a</td>\n",
" <td>9.50</td>\n",
" <td>898.0</td>\n",
" </tr>\n",
" <tr>\n",
" <th>0</th>\n",
" <td>American:245aa2f1</td>\n",
" <td>10.00</td>\n",
" <td>1292.0</td>\n",
" </tr>\n",
" <tr>\n",
" <th>4</th>\n",
" <td>Mushroom:b6b736c9</td>\n",
" <td>11.00</td>\n",
" <td>820.0</td>\n",
" </tr>\n",
" <tr>\n",
" <th>5</th>\n",
" <td>Pizza:71307a5a</td>\n",
" <td>11.00</td>\n",
" <td>838.0</td>\n",
" </tr>\n",
" </tbody>\n",
"</table>\n",
"</div>"
],
"text/plain": [
" Pizza hasPricevalue hasCalorificContentValuevalue\n",
"2 Margherita:3cfeae45 8.99 848.0\n",
"3 Margherita:e424656a 9.50 898.0\n",
"0 American:245aa2f1 10.00 1292.0\n",
"4 Mushroom:b6b736c9 11.00 820.0\n",
"5 Pizza:71307a5a 11.00 838.0"
]
},
"execution_count": 16,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"q = onto.query(g, onto.terms.pizza.Pizza,\n",
" [onto.terms.pizza.hasPrice,\n",
" onto.terms.pizza.hasCalorificContentValue],\n",
" python_values=True)\n",
"q.sort_values(\"hasPricevalue\").head()"
]
},
{
"cell_type": "code",
"execution_count": 17,
"id": "ad4f7ce6",
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"Pizza object\n",
"hasPricevalue float64\n",
"hasCalorificContentValuevalue float64\n",
"dtype: object"
]
},
"execution_count": 17,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"q.dtypes"
]
},
{
"cell_type": "markdown",
"metadata": {},
Expand All @@ -873,6 +1219,9 @@
"3. **Multiple Properties**: Query multiple properties simultaneously \n",
"4. **Nested Conditions**: Build sophisticated queries by nesting logical operators for complex filtering logic\n",
"5. **Class Selectors**: Control query behavior with `.all_subtypes`, `.any`, and `.only` to precisely target classes and hierarchies\n",
"6. **Independent Conditions**: Pass several conditions as separate destinations; all of them must hold\n",
"7. **Optional Properties**: Use `.optional` to keep items that lack a property\n",
"8. **Python Values**: Use `python_values=True` to get plain Python values and numeric columns\n",
"\n",
"These features allow you to construct complex SPARQL queries using intuitive Python syntax, making knowledge graph querying more accessible without requiring deep SPARQL expertise."
]
Expand Down
Loading
Loading