`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