Optimisations
Optimising Data Queries in the Knowledge Graph
This guide explains how to improve the performance of your API queries to
the DZT Knowledge Graph.
By applying the following steps, you can reduce response times, avoid timeouts,
and make your data access more efficient.
Step 1: Limit the Page Size
Why: Large page sizes increase response time and memory load on both client
and server.
How: Use the page-size header or query parameter to reduce the number of
results per page.
Example
-H 'page-size: 5'
Recommendation:
Start with 5–10 results per page and load additional pages iteratively.
Step 2: Control the Depth of Returned Data (X-HOP)
Why: By default, responses may include deeply nested linked objects, which
slows down responses.
How: Use the X-HOP header to define how many levels of linked entities should
be expanded.
X-HOP
| Value | Description | Recommended Use |
|---|---|---|
| 0 | Returns only object IDs and types | For simple lists or ID lookups |
| 1 | Returns direct linked objects | For moderate detail |
| 2+ | Includes nested relationships | Use only when necessary |
Example
-H 'X-HOP: 0'
This keeps the response lightweight and ideal for overviews or listings.
Step 3: Use Domain Specification Filters
Why: Filtering data by Domain Specification (DS) limits your query to relevant
content types.
How: Apply the filterDsList parameter to restrict your results.
Example
-H 'filterDsList: https://semantify.it/list/CRkyvcqGqeUu'
Result: You’ll receive only the objects that comply with the given DS,
significantly improving query speed and relevance.
Step 4: Combine Optimisations
For best results, combine all three techniques:
curl 'https://proxy.opendatagermany.io/api/ts/v2/kg/things?kw=castle' \
-H 'accept: application/json' \
-H 'x-api-key: <APIKEY>' \
-H 'page-size: 5' \
-H 'X-HOP: 0' \
-H 'filterDsList: https://semantify.it/list/CRkyvcqGqeUu'This example:
- Returns only 5 results per page
- Limits expansion to IDs (X-HOP: 0)
- Filters for one DS type
Step 5: Notes on API Versions
⚠️ Version 1 (V1) is deprecated.
Always use the /v2 endpoints.
Version 2 offers faster query processing, improved pagination, and better filter
handling.
Example:
/api/ts/v2/kg/things
Quick Reference
| Optimisation | Effect | Recommendation |
|---|---|---|
| Smaller pagesize | Reduces data load per request | 5–10 |
| Lower X-HOP | Limits nested objects | 0–1 for lists |
| filterDsList | Restricts to relevant types | Always apply |
| Use /v2 endpoint | Faster and stable | Required |
Final Checklist
Before sending your queries:
- Keep page-size small
- Use X-HOP: 0 or 1
- Apply filterDsList to focus results
- Prefer /v2 API endpoints
- Test your query step by step
See Also
Updated 44 minutes ago