Skip to main content
Glama

Raw CELLAR SPARQL Query

eurlex_query_sparql
Read-only

Run a raw, read-only SPARQL SELECT against the CELLAR Virtuoso endpoint — an escape hatch for CDM ontology traversals the curated tools do not cover. Only SELECT is accepted; update forms and ASK/CONSTRUCT/DESCRIBE are rejected before execution, and results are capped at the server row cap (100 by default). The cdm:, skos:, and xsd: prefixes are auto-injected.

Input Schema

NameRequiredDescriptionDefault
sparql_queryYesA read-only SPARQL SELECT query. Leading comments and PREFIX/BASE declarations are allowed; the cdm:, skos:, and xsd: prefixes are auto-injected. LIMIT is injected at the server row cap (100 unless the deployment configures a lower one) if absent, or capped to it; to read past the cap, add ORDER BY and repeat the query with OFFSET raised by the cap (a sorted query reaches row 10,000 at most). Key CDM predicates: cdm:resource_legal_id_celex (CELEX), cdm:work_date_document (date), cdm:work_has_resource-type (type), cdm:work_is_about_concept_eurovoc (EuroVoc subject), cdm:work_cites_work (citation). CELEX is an xsd:string literal — match it as a typed triple, ?work cdm:resource_legal_id_celex "32016R0679"^^xsd:string (an untyped literal matches nothing, in a triple or in FILTER(?celex = "…"), and a FILTER(STR(…)) comparison scans every CELEX). For text, use bif:contains with a single-quoted phrase.
timeout_hintNoOptional client-side timeout in milliseconds (1000–55000). The server default (55000 unless the deployment configures another value) applies when omitted.

Output Schema

NameRequiredDescriptionDefault
capNoThe server-enforced result ceiling that was applied.
errorNoPresent when the call failed. Absent on success.
shownNoNumber of binding rows returned in this response.
totalNoNumber of binding rows returned (at most the server's row cap, 100 by default).
noticeNoOn a truncated result: how to page past the row cap with ORDER BY and OFFSET, and the 10,000-row limit on a sorted query. On a zero-row result whose query has an untyped string literal as a triple object: how to type or language-tag it, since CELLAR stores identifiers as typed literals that an untyped one never matches.
bindingsNoRaw SPARQL binding rows. To extract a value from a row: row["varName"]?.value. Use the variables array to iterate in query order.
truncatedNoTrue when the server's row cap (the deployment's configured cap, 100 by default; cap gives the value applied) limited the rows and more may exist upstream — page on with ORDER BY in the query and OFFSET raised by the cap per call (sorted queries reach row 10,000 at most), or narrow the query with FILTERs.
variablesNoVariable names from the SELECT head, in query order.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed6 schema fields changed
    • changedInput schema / properties / sparql_query / description
      Previous value: -"A read-only SPARQL SELECT query. Leading comments and PREFIX/BASE declarations are allowed; the cdm:, skos:, and xsd: prefixes are auto-injected. LIMIT is injected at 100 if absent, or capped to 100. Key CDM predicates: cdm:resource_legal_id_celex (CELEX), cdm:work_date_document (date), cdm:work_has_resource-type (type), cdm:work_is_about_concept_eurovoc (EuroVoc subject), cdm:work_cites_work (citation). CELEX is an xsd:string literal — match it as a typed triple, ?work cdm:resource_legal_id_celex \"32016R0679\"^^xsd:string (an untyped literal matches nothing, in a triple or in FILTER(?celex = \"…\"), and a FILTER(STR(…)) comparison scans every CELEX). For text, use bif:contains with a single-quoted phrase."New value: +"A read-only SPARQL SELECT query. Leading comments and PREFIX/BASE declarations are allowed; the cdm:, skos:, and xsd: prefixes are auto-injected. LIMIT is injected at the server row cap (100 unless the deployment configures a lower one) if absent, or capped to it; to read past the cap, add ORDER BY and repeat the query with OFFSET raised by the cap (a sorted query reaches row 10,000 at most). Key CDM predicates: cdm:resource_legal_id_celex (CELEX), cdm:work_date_document (date), cdm:work_has_resource-type (type), cdm:work_is_about_concept_eurovoc (EuroVoc subject), cdm:work_cites_work (citation). CELEX is an xsd:string literal — match it as a typed triple, ?work cdm:resource_legal_id_celex \"32016R0679\"^^xsd:string (an untyped literal matches nothing, in a triple or in FILTER(?celex = \"…\"), and a FILTER(STR(…)) comparison scans every CELEX). For text, use bif:contains with a single-quoted phrase."
    • changedInput schema / properties / timeout_hint / description
      Previous value: -"Optional client-side timeout in milliseconds (1000–55000). Defaults apply when omitted; the endpoint hard limit is 60 seconds."New value: +"Optional client-side timeout in milliseconds (1000–55000). The server default (55000 unless the deployment configures another value) applies when omitted."
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `not_read_only`: The query is a SPARQL Update operation (INSERT, DELETE, WITH, LOAD, CLEAR, CREATE, DROP, COPY, MOVE, or ADD). `unsupported_query_form`: The query is not a SELECT: an ASK, CONSTRUCT, or DESCRIBE form, an unrecognized keyword, or no query keyword after the prologue. `sparql_error`: Virtuoso returned a syntax or semantic error — the query is malformed. `sparql_timeout`: The query exceeded the client-side timeout (timeout_hint, default 55 s) or the 60-second Virtuoso execution limit. Neither is retried: the call fails inside the configured bound. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `not_read_only`: The query is a SPARQL Update operation (INSERT, DELETE, WITH, LOAD, CLEAR, CREATE, DROP, COPY, MOVE, or ADD). `unsupported_query_form`: The query is not a SELECT: an ASK, CONSTRUCT, or DESCRIBE form, an unrecognized keyword, or no query keyword after the prologue. `sparql_error`: CELLAR rejected the query: a syntax or semantic error, a compile error, or a sorted query whose OFFSET + LIMIT passes row 10,000 (SR353, answered with its own recovery: lower OFFSET or narrow the query). The same query fails the same way again. `sparql_timeout`: The query ran past the client-side timeout (timeout_hint, default 55 s), or Virtuoso refused it as over its estimated-cost limit. Neither is retried: the call fails inside the configured bound. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / notice / description
      Previous value: -"On a zero-row result whose query has an untyped string literal as a triple object: how to type or language-tag it, since CELLAR stores identifiers as typed literals that an untyped one never matches."New value: +"On a truncated result: how to page past the row cap with ORDER BY and OFFSET, and the 10,000-row limit on a sorted query. On a zero-row result whose query has an untyped string literal as a triple object: how to type or language-tag it, since CELLAR stores identifiers as typed literals that an untyped one never matches."
    • changedOutput schema / properties / total / description
      Previous value: -"Number of binding rows returned (capped at 100 by the server)."New value: +"Number of binding rows returned (at most the server's row cap, 100 by default)."
    • changedOutput schema / properties / truncated / description
      Previous value: -"True when the server-enforced result ceiling capped the rows and more may exist upstream — narrow the query with FILTERs to see the rest."New value: +"True when the server's row cap (the deployment's configured cap, 100 by default; cap gives the value applied) limited the rows and more may exist upstream — page on with ORDER BY in the query and OFFSET raised by the cap per call (sorted queries reach row 10,000 at most), or narrow the query with FILTERs."
  2. Changed4 schema fields changed
    • changedInput schema / properties / sparql_query / description
      Previous value: -"A read-only SPARQL SELECT query. Leading comments and PREFIX/BASE declarations are allowed; the cdm:, skos:, and xsd: prefixes are auto-injected. LIMIT is injected at 100 if absent, or capped to 100. Key CDM predicates: cdm:resource_legal_id_celex (CELEX), cdm:work_date_document (date), cdm:work_has_resource-type (type), cdm:work_is_about_concept_eurovoc (EuroVoc subject), cdm:work_cites_work (citation). CELEX is an xsd:string literal — match it as a typed triple, ?work cdm:resource_legal_id_celex \"32016R0679\"^^xsd:string (an untyped literal matches nothing, and a FILTER(STR(…)) comparison scans every CELEX). For text, use bif:contains with a single-quoted phrase."New value: +"A read-only SPARQL SELECT query. Leading comments and PREFIX/BASE declarations are allowed; the cdm:, skos:, and xsd: prefixes are auto-injected. LIMIT is injected at 100 if absent, or capped to 100. Key CDM predicates: cdm:resource_legal_id_celex (CELEX), cdm:work_date_document (date), cdm:work_has_resource-type (type), cdm:work_is_about_concept_eurovoc (EuroVoc subject), cdm:work_cites_work (citation). CELEX is an xsd:string literal — match it as a typed triple, ?work cdm:resource_legal_id_celex \"32016R0679\"^^xsd:string (an untyped literal matches nothing, in a triple or in FILTER(?celex = \"…\"), and a FILTER(STR(…)) comparison scans every CELEX). For text, use bif:contains with a single-quoted phrase."
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `not_read_only`: The query is not a read-only SELECT — an update or non-SELECT query form was supplied. `sparql_error`: Virtuoso returned a syntax or semantic error — the query is malformed. `sparql_timeout`: The query exceeded the client-side timeout (timeout_hint, default 55 s) or the 60-second Virtuoso execution limit. Neither is retried: the call fails inside the configured bound. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `not_read_only`: The query is a SPARQL Update operation (INSERT, DELETE, WITH, LOAD, CLEAR, CREATE, DROP, COPY, MOVE, or ADD). `unsupported_query_form`: The query is not a SELECT: an ASK, CONSTRUCT, or DESCRIBE form, an unrecognized keyword, or no query keyword after the prologue. `sparql_error`: Virtuoso returned a syntax or semantic error — the query is malformed. `sparql_timeout`: The query exceeded the client-side timeout (timeout_hint, default 55 s) or the 60-second Virtuoso execution limit. Neither is retried: the call fails inside the configured bound. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
      -  "not_read_only",
      -  "sparql_error",
      -  "sparql_timeout"
      -]New value: +[
      +  "not_read_only",
      +  "unsupported_query_form",
      +  "sparql_error",
      +  "sparql_timeout"
      +]
    • addedOutput schema / properties / notice
      Added value: +{
      +  "description": "On a zero-row result whose query has an untyped string literal as a triple object: how to type or language-tag it, since CELLAR stores identifiers as typed literals that an untyped one never matches.",
      +  "type": "string"
      +}
  3. Changed1 schema field changed
    • changedInput schema / properties / sparql_query / description
      Previous value: -"A read-only SPARQL SELECT query. Leading comments and PREFIX/BASE declarations are allowed; the cdm:, skos:, and xsd: prefixes are auto-injected. LIMIT is injected at 100 if absent, or capped to 100. Key CDM predicates: cdm:resource_legal_id_celex (CELEX), cdm:work_date_document (date), cdm:work_has_resource-type (type), cdm:work_is_about_concept_eurovoc (EuroVoc subject), cdm:work_cites_work (citation). CELEX is an xsd:string literal — match it with FILTER(STR(?celex) = \"…\"). For text, use bif:contains with a single-quoted phrase."New value: +"A read-only SPARQL SELECT query. Leading comments and PREFIX/BASE declarations are allowed; the cdm:, skos:, and xsd: prefixes are auto-injected. LIMIT is injected at 100 if absent, or capped to 100. Key CDM predicates: cdm:resource_legal_id_celex (CELEX), cdm:work_date_document (date), cdm:work_has_resource-type (type), cdm:work_is_about_concept_eurovoc (EuroVoc subject), cdm:work_cites_work (citation). CELEX is an xsd:string literal — match it as a typed triple, ?work cdm:resource_legal_id_celex \"32016R0679\"^^xsd:string (an untyped literal matches nothing, and a FILTER(STR(…)) comparison scans every CELEX). For text, use bif:contains with a single-quoted phrase."
  4. Changed1 schema field changed
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `not_read_only`: The query is not a read-only SELECT — an update or non-SELECT query form was supplied. `sparql_error`: Virtuoso returned a syntax or semantic error — the query is malformed. `sparql_timeout`: Query exceeded the 60-second Virtuoso hard limit. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `not_read_only`: The query is not a read-only SELECT — an update or non-SELECT query form was supplied. `sparql_error`: Virtuoso returned a syntax or semantic error — the query is malformed. `sparql_timeout`: The query exceeded the client-side timeout (timeout_hint, default 55 s) or the 60-second Virtuoso execution limit. Neither is retried: the call fails inside the configured bound. Other values are possible when a failure originates below the handler."
  5. Changed6 schema fields changed
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedInput schema / additionalProperties
      Added value: +false
    • changedOutput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedOutput schema / anyOf
      Added value: +[
      +  {
      +    "not": {
      +      "required": [
      +        "error"
      +      ]
      +    },
      +    "required": [
      +      "bindings",
      +      "variables",
      +      "total"
      +    ]
      +  },
      +  {
      +    "required": [
      +      "error"
      +    ]
      +  }
      +]
    • addedOutput schema / properties / error
      Added value: +{
      +  "additionalProperties": {},
      +  "description": "Present when the call failed. Absent on success.",
      +  "properties": {
      +    "code": {
      +      "description": "JSON-RPC error code for this failure.",
      +      "maximum": 9007199254740991,
      +      "minimum": -9007199254740991,
      +      "type": "integer"
      +    },
      +    "data": {
      +      "additionalProperties": {},
      +      "properties": {
      +        "reason": {
      +          "description": "Machine-readable failure mode. Declared by this tool: `not_read_only`: The query is not a read-only SELECT — an update or non-SELECT query form was supplied. `sparql_error`: Virtuoso returned a syntax or semantic error — the query is malformed. `sparql_timeout`: Query exceeded the 60-second Virtuoso hard limit. Other values are possible when a failure originates below the handler.",
      +          "examples": [
      +            "not_read_only",
      +            "sparql_error",
      +            "sparql_timeout"
      +          ],
      +          "type": "string"
      +        },
      +        "recovery": {
      +          "additionalProperties": {},
      +          "description": "Actionable next step for the caller.",
      +          "properties": {
      +            "hint": {
      +              "type": "string"
      +            }
      +          },
      +          "required": [
      +            "hint"
      +          ],
      +          "type": "object"
      +        },
      +        "retryable": {
      +          "description": "Whether retrying may succeed.",
      +          "type": "boolean"
      +        }
      +      },
      +      "type": "object"
      +    },
      +    "message": {
      +      "description": "Human-readable description of what went wrong.",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "code",
      +    "message"
      +  ],
      +  "type": "object"
      +}
    • removedOutput schema / required
      Removed value: -[
      -  "bindings",
      -  "variables",
      -  "total"
      -]
  6. Changed4 schema fields changed
    • changedOutput schema / properties / bindings / items / description
      Previous value: -"A single SPARQL result row. Each key is a SELECT variable name; each value is a SPARQL term object with \"type\" (e.g. \"uri\", \"literal\") and \"value\" (the string value) fields."New value: +"A single SPARQL result row. Each key is a SELECT variable name; each value is a SPARQL term object with \"type\" (\"uri\", \"literal\", or \"bnode\") and \"value\" (the string value), plus \"datatype\" (an IRI) on a typed literal or \"xml:lang\" (a language tag) on a language-tagged literal — the two are mutually exclusive. A variable left unbound by an OPTIONAL has no key in the row at all."
    • addedOutput schema / properties / cap
      Added value: +{
      +  "description": "The server-enforced result ceiling that was applied.",
      +  "type": "number"
      +}
    • addedOutput schema / properties / shown
      Added value: +{
      +  "description": "Number of binding rows returned in this response.",
      +  "type": "number"
      +}
    • addedOutput schema / properties / truncated
      Added value: +{
      +  "description": "True when the server-enforced result ceiling capped the rows and more may exist upstream — narrow the query with FILTERs to see the rest.",
      +  "type": "boolean"
      +}
  7. Changed2 schema fields changed
    • changedInput schema / properties / sparql_query / description
      Previous value: -"A read-only SPARQL SELECT query to execute against CELLAR. Non-SELECT queries (updates such as DELETE/INSERT, or ASK/CONSTRUCT/DESCRIBE) are rejected before execution. Leading comments and PREFIX/BASE declarations are allowed before the SELECT keyword. The cdm:, skos:, and xsd: prefixes are auto-injected. LIMIT is injected at 100 if absent or capped to 100 if above that threshold."New value: +"A read-only SPARQL SELECT query. Leading comments and PREFIX/BASE declarations are allowed; the cdm:, skos:, and xsd: prefixes are auto-injected. LIMIT is injected at 100 if absent, or capped to 100. Key CDM predicates: cdm:resource_legal_id_celex (CELEX), cdm:work_date_document (date), cdm:work_has_resource-type (type), cdm:work_is_about_concept_eurovoc (EuroVoc subject), cdm:work_cites_work (citation). CELEX is an xsd:string literal — match it with FILTER(STR(?celex) = \"…\"). For text, use bif:contains with a single-quoted phrase."
    • changedInput schema / properties / timeout_hint / description
      Previous value: -"Optional client-side timeout for this request, in milliseconds (1000–55000). When omitted, the default timeout applies; the endpoint hard limit is 60 seconds."New value: +"Optional client-side timeout in milliseconds (1000–55000). Defaults apply when omitted; the endpoint hard limit is 60 seconds."
  8. Changed1 schema field changed
    • changedInput schema / properties / timeout_hint / description
      Previous value: -"Optional client-side timeout for this request, in milliseconds (1000–55000). When omitted, the server-configured default (SPARQL_QUERY_TIMEOUT_MS, 55000) applies. Virtuoso hard limit is 60 seconds."New value: +"Optional client-side timeout for this request, in milliseconds (1000–55000). When omitted, the default timeout applies; the endpoint hard limit is 60 seconds."
  9. Changed2 schema fields changed
    • changedInput schema / properties / sparql_query / description
      Previous value: -"A SPARQL SELECT query to execute against CELLAR. The cdm:, skos:, and xsd: prefixes are auto-injected. LIMIT is injected at 100 if absent or capped to 100 if above that threshold."New value: +"A read-only SPARQL SELECT query to execute against CELLAR. Non-SELECT queries (updates such as DELETE/INSERT, or ASK/CONSTRUCT/DESCRIBE) are rejected before execution. Leading comments and PREFIX/BASE declarations are allowed before the SELECT keyword. The cdm:, skos:, and xsd: prefixes are auto-injected. LIMIT is injected at 100 if absent or capped to 100 if above that threshold."
    • changedInput schema / properties / timeout_hint / description
      Previous value: -"Optional client-side timeout hint in milliseconds (1000–55000). Defaults to server-configured SPARQL_QUERY_TIMEOUT_MS (55000). Virtuoso hard limit is 60 seconds."New value: +"Optional client-side timeout for this request, in milliseconds (1000–55000). When omitted, the server-configured default (SPARQL_QUERY_TIMEOUT_MS, 55000) applies. Virtuoso hard limit is 60 seconds."
  10. First observed

TDQS

A4.5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the readOnlyHint/openWorldHint annotations: only SELECT is accepted, update forms and ASK/CONSTRUCT/DESCRIBE are rejected pre-execution, results are capped at the server row cap (100 default), and cdm:/skos:/xsd: prefixes are auto-injected. These are exactly the operational traits an agent needs before issuing a raw query.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences with zero filler: purpose and positioning first, execution constraints second, prefix behavior last. The most decision-relevant information (read-only, SELECT-only) is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a raw-query escape hatch with a rich output schema already present, the description covers what an agent must know: acceptance/rejection rules, result capping, and prefix injection. Return-value explanation is correctly omitted since the output schema exists.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents both parameters in depth (LIMIT injection, prefix auto-injection, timeout range). The description's mention of the row cap and auto-injected prefixes restates what the schema provides rather than adding new parameter meaning, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Run a raw, read-only SPARQL SELECT against the CELLAR Virtuoso endpoint') and explicitly positions itself against the siblings as 'an escape hatch for CDM ontology traversals the curated tools do not cover.' An agent can distinguish it from eurlex_search_documents or eurlex_get_relations without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives a clear when-to-use condition ('traversals the curated tools do not cover'), which routes the agent away from the curated siblings toward this tool for advanced cases. It stops short of naming which sibling handles what, so there is no explicit when-not/alternative mapping, but the context is unambiguous.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.