datasets

Query Dataset With Sparql

Run a read-only SPARQL query over a dataset’s knowledge graph.

The dataset graph is read in full and loaded into an in-memory RDF store for the duration of the request (the same view cognee.modules.graph.rdf exports), then the query runs there. Nodes carrying an ontology_uri keep that IRI; other nodes get {base_iri}node/{id} and cognee-native edges {base_iri}prop/{relationship_name}; name becomes rdfs:label and is_a becomes rdf:type / rdfs:subClassOf.

Path Parameters

dataset_id (UUID): The unique identifier of the dataset

Request Body

query (str): SELECT, ASK, CONSTRUCT or DESCRIBE. SPARQL Update (INSERT, DELETE, LOAD, CLEAR, DROP, CREATE, ADD, MOVE, COPY) is refused, and so are SERVICE, FROM and FROM NAMED: the query reads this dataset’s graph only.
base_iri (str, optional): prefix for minted IRIs
limit (int, 1-10000, default 1000): cap on SELECT rows

Response

Depends on the query form:

SELECT: variables, rows, row_count, truncated
ASK: boolean
CONSTRUCT / DESCRIBE: turtle

Limits

Graphs with more than SPARQL_MAX_GRAPH_NODES nodes (default 200000) are refused with 413; export the graph as RDF instead.
Queries that run longer than SPARQL_QUERY_TIMEOUT_SECONDS (default 30) are abandoned with 504. The server stops waiting; the worker thread finishes on its own.

Error Codes

400 Bad Request: SPARQL Update keywords, SERVICE / FROM / FROM NAMED, or the query does not parse
404 Not Found: Dataset doesn’t exist or user doesn’t have access
413 Content Too Large: Dataset graph exceeds the node ceiling
504 Gateway Timeout: Query exceeded the wall-clock budget

POST

api

datasets

{dataset_id}

sparql

Query Dataset With Sparql

curl --request POST \
  --url https://{tenant}.aws.cognee.ai/api/v1/datasets/{dataset_id}/sparql \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "SELECT ?s ?name WHERE { ?s rdfs:label ?name } LIMIT 10"
}
'

import requests

url = "https://{tenant}.aws.cognee.ai/api/v1/datasets/{dataset_id}/sparql"

payload = { "query": "SELECT ?s ?name WHERE { ?s rdfs:label ?name } LIMIT 10" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "variables": [
    "<string>"
  ],
  "rows": [
    [
      "<string>"
    ]
  ],
  "row_count": 123,
  "truncated": true,
  "boolean": true,
  "turtle": "<string>"
}

{
  "message": "<string>"
}

{
  "message": "<string>"
}

{
  "message": "<string>"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

{
  "message": "<string>"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

dataset_id

string<uuid>

required

Dataset UUID, the id field from GET /api/v1/datasets (not the name)

Example:

"b8a7c3de-4f5a-4b6c-8d9e-0f1a2b3c4d5e"

Body

application/json

query

string

required

A read-only SPARQL 1.1 query: SELECT, ASK, CONSTRUCT or DESCRIBE.

Minimum string length: 1

Example:

"SELECT ?s ?name WHERE { ?s rdfs:label ?name } LIMIT 10"

baseIri

string | null

Prefix for the IRIs minted for nodes without an ontology_uri and for cognee-native predicates. Defaults to https://cognee.ai/graph/.

Example:

"https://example.org/memory/"

limit

integer

default:1000

Maximum number of SELECT rows to return; sets truncated when hit.

Required range: 1 <= x <= 10000

Response

Successful Response

One query form's result; the fields for the other forms are omitted.

Keys are deliberately snake_case (not the API's usual camelCase): they mirror the SPARQL JSON results vocabulary callers already parse.

variables

string[] | null

SELECT: projected names

rows

((string | null)[])[] | null

SELECT: one list per solution, aligned with variables. IRIs and literal lexical forms as strings, blank nodes as _:id, unbound as null.

row_count

integer | null

SELECT: len(rows)

truncated

boolean | null

SELECT: true when more rows existed than limit

boolean

boolean | null

ASK: the answer

turtle

string | null

CONSTRUCT / DESCRIBE: the result graph as Turtle

⌘I

Query Dataset With Sparql

curl --request POST \
  --url https://{tenant}.aws.cognee.ai/api/v1/datasets/{dataset_id}/sparql \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "SELECT ?s ?name WHERE { ?s rdfs:label ?name } LIMIT 10"
}
'

import requests

url = "https://{tenant}.aws.cognee.ai/api/v1/datasets/{dataset_id}/sparql"

payload = { "query": "SELECT ?s ?name WHERE { ?s rdfs:label ?name } LIMIT 10" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "variables": [
    "<string>"
  ],
  "rows": [
    [
      "<string>"
    ]
  ],
  "row_count": 123,
  "truncated": true,
  "boolean": true,
  "turtle": "<string>"
}

{
  "message": "<string>"
}

{
  "message": "<string>"
}

{
  "message": "<string>"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

{
  "message": "<string>"
}