🔍 SQL Queries

SQL is the primary query language. RelataDB extends it with bi-temporal, graph, identity, and search operators — all reachable through query().

Plain SQL

result = client.query("SELECT name, role, company FROM Person WHERE risk = 'HIGH'")
for row in result:
    print(row["name"], row["role"])
{"data": [
  {"name": "Alice Chen", "role": "CFO",      "company": "Acme Corp"},
  {"name": "Bob Smith",  "role": "Director", "company": "ShellCo Ltd"}
]}

Aggregates

client.query("SELECT SUM(amount) FROM Transaction")
# {"data": [{"SUM(amount)": 3770000}]}
 
client.query(
    "SELECT from_account, COUNT(*), SUM(amount) "
    "FROM Transaction GROUP BY from_account"
)
{"data": [
  {"from_account": "Acme Corp",           "COUNT(*)": 2, "SUM(amount)": 2800000},
  {"from_account": "Pacific Trust 7742",  "COUNT(*)": 1, "SUM(amount)": 850000},
  {"from_account": "ShellCo Ltd",         "COUNT(*)": 1, "SUM(amount)": 120000}
]}

$3.77 million moved. The trail: Acme → offshore → shell company → cash.

Parameterized query (no SQL injection)

result = client.query_params(
    "SELECT name, role FROM Person WHERE risk = $1 AND company = $2",
    ["HIGH", "Acme Corp"],
)
# ?-placeholders are rewritten to $1, $2, … automatically:
client.query_params("SELECT * FROM Person WHERE id = ?", ["alice"])

Typed select helper (fluent builder)

result = (
    client.select("name", "risk")
         .from_("Person")
         .where("risk = 'HIGH'")
         .order_by("name")
         .limit(10)
         .execute()
)

Arrow IPC (zero-copy, large result sets)

tbl = client.query_arrow("SELECT * FROM Transaction LIMIT 1000")
df = tbl.to_pandas()   # requires pyarrow

Federated multi-query

client.multi_search({
    "queries": [
        {"query": "alice",       "type": "Person",      "limit": 5},
        {"query": "embezzlement","type": "CaseDoc",     "limit": 5},
        {"query": "pacific trust","type": "Transaction","limit": 5},
    ],
})
# {"results": [<SearchResponse>, <SearchResponse>, ...],
#  "processing_time_ms": 7.2}

GraphQL

client.graphql("""
  query {
    Person(where: { risk: { _eq: "HIGH" } }, limit: 10) {
      id name role company
    }
  }
""")

SPARQL

client.sparql("""
  PREFIX rel: <https://relata.io/ns#>
  SELECT ?s ?o WHERE { ?s rel:authorizedBy ?o } LIMIT 5
""")
MethodWireReturns
query(sql)POST /queryQueryResult (iterable)
query_params(sql, params)POST /query (positional binds)QueryResult
query_arrow(sql)POST /query/arrowpyarrow.Table
multi_search(queries)POST /multi-searchdict
graphql(q)POST /graphqldata field
sparql(q)POST /sparqldict

Next: Hybrid Search — BM25 with facets and the fused BM25+vector HYBRID_SEARCH operator.