Query & SQL

Every query runs through the governed path — ACL, cell masking, audit — and carries an optional PURPOSE. SQL is the primary door; GraphQL/SPARQL/Cypher are auto-routed. Bi-temporal AS OF time-travel and WITH PROVENANCE are first-class on every read.

Note
Async mirrors: every method has an a-prefixed async twin (query → aquery) with the identical signature and semantics on Python.

15 methods across this domain. Signatures, parameters (incl. keyword-only tunable defaults), and the three SDK spellings are ported from the live SDK source; flagship methods carry a hand-written When to use + example.

FlightClient

query_flight(sql, flight_endpoint=None, purpose=None, bearer_token=None)

query_flight(sql, flight_endpoint=None, purpose=None, bearer_token=None)`

  • Python — client.flightclient.query_flight(sql, flight_endpoint=None, purpose=None, bearer_token=None)

Parameters: sql, flight_endpoint=None, purpose=None, bearer_token=None

RelataClient

query(sql, purpose=None)

When to use. You have raw SQL or a Cypher/GraphQL/SPARQL string and want the governed result as iterable rows.

  • Python — client.relataclient.query(sql, purpose=None)
  • Go — Query(sql)

Parameters: sql, purpose=None

Example

for row in relata.query("SELECT * FROM Person WHERE nationality = 'IN' LIMIT 10", purpose="analytics"):
    print(row["name"])
const rows = await relata.query("SELECT * FROM Person LIMIT 10", { purpose: "analytics" });
res, _ := relata.Query(ctx, "SELECT * FROM Person LIMIT 10")
for _, row := range res.Rows {
    fmt.Println(row["name"])
}

query_arrow(sql, purpose=None)

When to use. You want a zero-copy pyarrow.Table for analytics / pandas / Flight interchange.

  • Python — client.relataclient.query_arrow(sql, purpose=None)

Parameters: sql, purpose=None

Example

import pyarrow as pa
table: pa.Table = relata.query_arrow("SELECT * FROM Person")
df = table.to_pandas()

query_flight(sql, flight_endpoint=None, purpose=None, bearer_token=None)

When to use. Bulk-pull or stream large results over gRPC (Arrow Flight) — the highest-throughput door.

  • Python — client.relataclient.query_flight(sql, flight_endpoint=None, purpose=None, bearer_token=None)
  • Go — QueryFlight(sql, flightEndpoint, purpose, bearer)

Parameters: sql, flight_endpoint=None, purpose=None, bearer_token=None

Example

table = relata.query_flight("SELECT * FROM TradeHistory")

query_params(sql, params, purpose=None)

When to use. You have untrusted values — bind them. ? placeholders auto-rewrite to $N server-side.

  • Python — client.relataclient.query_params(sql, params, purpose=None)

Parameters: sql, params, purpose=None

Example

rows = relata.query_params("SELECT * FROM Person WHERE nationality = ? AND age > ?", ['IN', 25])
res, _ := relata.QueryWithParams(ctx, "SELECT * FROM Person WHERE nationality = $1 AND age > $2", []any{"IN", 25})

create_schema_branch(name, from_branch)

create_schema_branch(name, from_branch)`

  • Python — client.relataclient.create_schema_branch(name, from_branch)
  • TypeScript — createSchemaBranch(name, fromBranch)
  • Go — CreateSchemaBranch(name, fromBranch)

Parameters: name, from_branch

delete_schema_branch(name)

delete_schema_branch(name)`

  • Python — client.relataclient.delete_schema_branch(name)
  • TypeScript — deleteSchemaBranch(name)
  • Go — DeleteSchemaBranch(name)

Parameters: name

export_data(object_type, format="json")

export_data(object_type, format="json")`

  • Python — client.relataclient.export_data(object_type, format="json")
  • TypeScript — exportData(objectType, format)
  • Go — ExportData(objectType, format)

Parameters: object_type, format="json"

graphql(query, variables=None, operation_name=None)

graphql(query, variables=None, operation_name=None)`

  • Python — client.relataclient.graphql(query, variables=None, operation_name=None)
  • TypeScript — graphql(query, variables, operationName)
  • Go — GraphQL(gqlQuery, variables, operationName)

Parameters: query, variables=None, operation_name=None

namespace(name)

namespace(name)`

  • Python — client.relataclient.namespace(name)
  • TypeScript — namespace(name)
  • Go — Namespace(name)

Parameters: name

select(*columns_or_table: str)

select(*columns_or_table: str)`

  • Python — client.relataclient.select(*columns_or_table: str)
  • TypeScript — select(type)

Parameters: *columns_or_table: str

session_commit(session_id)

session_commit(session_id)`

  • Python — client.relataclient.session_commit(session_id)
  • TypeScript — sessionCommit(sessionId)
  • Go — SessionCommit(sessionID)

Parameters: session_id

session_diff(session_id)

session_diff(session_id)`

  • Python — client.relataclient.session_diff(session_id)
  • TypeScript — sessionDiff(sessionId)
  • Go — SessionDiff(sessionID)

Parameters: session_id

session_discard(session_id)

session_discard(session_id)`

  • Python — client.relataclient.session_discard(session_id)
  • TypeScript — sessionDiscard(sessionId)
  • Go — SessionDiscard(sessionID)

Parameters: session_id

sparql(query)

sparql(query)`

  • Python — client.relataclient.sparql(query)
  • TypeScript — sparql(query)
  • Go — Sparql(query)

Parameters: query