hydrai:ExampleQuery

A worked query a client can learn from: a natural-language intent, the query text, and the endpoint it runs against. Few-shot orientation, expressed as data.

This page is a companion to the namespace entry. The definitions and shape below are generated from agent.ttl at build time.

The authoritative definitions

hydrai:ExampleQuery

class

example query

A worked query a client can learn from: a natural-language intent, the query text, and the endpoint it runs against. Few-shot orientation, expressed as data. Executable content: a consumer NEVER runs it verbatim — an example is a candidate routed through the consumer's query gates and executed only under the consumer's own authority (see §8.3). Structural constraints (ExampleQueryShape) are coarse defence-in-depth; they do not make a query safe.

IRI
https://hydrai.org/ns/agent#ExampleQuery
type
rdfs:Class, owl:Class

defined by https://hydrai.org/ns/agent · see also https://hydrai.org/docs/example-query

hydrai:exampleQuery

object property

example query

Relates a service or collection to an example query it offers.

IRI
https://hydrai.org/ns/agent#exampleQuery
type
rdf:Property, owl:ObjectProperty

range
hydrai:ExampleQuery

defined by https://hydrai.org/ns/agent

hydrai:intent

datatype property

The natural-language purpose an example query answers.

IRI
https://hydrai.org/ns/agent#intent
type
rdf:Property, owl:DatatypeProperty

range
xsd:string

defined by https://hydrai.org/ns/agent

hydrai:queryText

datatype property

query text

The query string (SPARQL in 0.1). Coarsely constrained by shape (read verb, no obvious mutation keyword, length); safety is enforced at EXECUTION, not by the shape — SPARQL is not a regular language and a read-only query can still exfiltrate via SERVICE federation.

IRI
https://hydrai.org/ns/agent#queryText
type
rdf:Property, owl:DatatypeProperty

range
xsd:string

defined by https://hydrai.org/ns/agent

hydrai:overEndpoint

object property

over endpoint

The endpoint an example query runs against.

IRI
https://hydrai.org/ns/agent#overEndpoint
type
rdf:Property, owl:ObjectProperty

defined by https://hydrai.org/ns/agent

hydrai:ExampleQueryShape

SHACL shape

COARSE structural constraint only — defence-in-depth, never a safety guarantee. Requires a read verb, forbids the obvious mutation keywords, caps length, types the endpoint. It does NOT and CANNOT catch SERVICE-clause exfiltration; execution containment is the real wall.

targets hydrai:ExampleQuery

  • sh:path hydrai:intent
  • sh:datatype xsd:string
  • sh:maxLength 140
  • sh:maxCount 1
  • sh:path hydrai:overEndpoint
  • sh:maxCount 1
  • sh:nodeKind sh:IRI
  • sh:path hydrai:queryText
  • sh:datatype xsd:string
  • sh:maxLength 2000
  • sh:maxCount 1
  • sh:minCount 1
  • sh:pattern ^\s*(SELECT|ASK|CONSTRUCT|DESCRIBE)
  • sh:flags i
  • sh:not [ sh:pattern (?i)\b(INSERT|DELETE|DROP|CLEAR|LOAD|CREATE)\b ]

How to use it

Few-shot is how an agent orients. exampleQuery is the hypermedia-native way to advertise it: an (intent, query, endpoint) tuple carried as data, so the one hand-written orchestration block a client used to carry becomes served, versioned, projectable content.

@prefix hydrai: <https://hydrai.org/ns/agent#> .
@prefix schema: <https://schema.org/> .

</Api/> hydrai:exampleQuery [
    a hydrai:ExampleQuery ;
    hydrai:intent      "Contacts created this quarter, most recent first" ;
    hydrai:queryText   "SELECT ?c WHERE { ?c a schema:Person ; schema:dateCreated ?d . FILTER(?d >= '2026-07-01') } ORDER BY DESC(?d)" ;
    hydrai:overEndpoint <https://example.org/sparql> ;
] .

Executable content is never run verbatim

An exampleQuery is executable, and that is exactly why a consumer never runs it as-is. It is a candidate routed through the consumer's own query gates and executed only under the consumer's own authority. The ExampleQueryShape above is coarse, defence-in-depth structural validation — it requires a read verb, forbids the obvious mutation keywords, caps length, and types the endpoint.

The shape does not make a query safe. SPARQL is not a regular language, and a read-only query can still exfiltrate via SERVICE federation. Safety is enforced at execution, in the client's query containment — not by the shape. The shape is a coarse filter; the execution gate is the real wall. See the safety posture.

Bound semantics

The one thing core Hydra genuinely cannot say about a template variable — that two variables are the ends of a range over one property — is expressed with lowerBoundOf / upperBoundOf (harvest pending):

[] hydrai:lowerBoundOf schema:dateCreated .   # ?from  →  ?d >= ?from
[] hydrai:upperBoundOf schema:dateCreated .   # ?to    →  ?d <= ?to