SQL API reference

Every capability is reachable from plain SQL. The Studio and any agent integration are conveniences over this surface, not privileged paths.

Generate this list yourself:

SELECT p.proname || '(' || pg_get_function_arguments(p.oid) || ') -> '
                 || pg_get_function_result(p.oid)
  FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace
 WHERE n.nspname = 'public' AND p.proname LIKE 'og\_%'
 ORDER BY 1;

Graphs and types — spec 002

Property types: string, int, long, float, bool, datetime, date, uuid, numeric, jsonb, text[], int[], vector(N).

Inheritance

Data — spec 001

Traversal and identifiers

Cypher picks between og_vlp and og_reach on its own: og_reach when the query binds no path or relationship variable, its projection cannot observe how many paths reach a node, and the depth is past where enumeration is cheaper. Nothing routes to og_csr_* automatically, because a compiled graph is a frozen snapshot that row-level security is never consulted about — that is a choice a caller makes explicitly. og_reach and the og_csr_* functions are PARALLEL RESTRICTED; a plan containing one runs in the leader. Numbers and the full rule: deep-traversal.md.

Operations

Cypher — spec 003

TypeQL — spec 010

TypeDB 3.x TypeQL over the same graph, catalog and transaction. See typeql.md for the supported syntax and the storage mapping.

Vectors — spec 004

Metrics: cosine (<=>), l2 (<->), ip (<#>). Scores are normalised so higher is always better.

Interoperability — spec 005

Views: og_node_view, og_edge_view, og_type_view, og_property_view, og_role_view.

Semantic web — spec 006

Agents — spec 008

Audit log: og_data.og_audit records every og_cypher and og_typeql call with principal (session_user), query, row count, duration and error code — and, since spec 014, db_user (the caller's current_user, accepted only if session_user is a member of it), actor, source and request_id (from the og.* settings, application-asserted), schema_version (the database-wide schema version sequence, not the graph's) and action (the Action the write came through). Rows are written only through the SECURITY DEFINER og__audit; write-level roles hold no DML on og_audit, og_history, og_source or the h_* history tables. Two limits: a failed query's audit row is rolled back with the query (SEC-18), and any reader may call og__audit directly and so append rows with caller-chosen query text — rows cannot be edited or deleted, but their content is not proof.

For spec 008's og_as_of: it now returns NULL at an instant after the entity was deleted, and breaks ties within one transaction by hist_id. Subtypes created after og_enable_history are captured too.

Schema evolution — spec 012

A schema change on a populated graph is four calls — expand, migrate, validate, contract — and one row in og_catalog.schema_change that records where it stands. Most kinds are catalog edits whose cost does not depend on the amount of data; only alter_property_type (and set_required with a default) rewrite rows, in batches. See ADR-028.

Phases: planned → expanded → migrating → validated → contracted, or aborted from any phase before contracted. Calling one out of order raises OG_SCHEMA_PHASE (SQLSTATE 55000).

A property can be dropped, renamed or retyped only on the type that declares it. Not supported: splitting or merging types, TypeQL redefine/undefine through this pipeline, hierarchy-wide uniqueness. og_create_index, og_map_table and og_materialize_mapping now bump the schema version, so cached Cypher plans are invalidated.

Temporal — spec 013

Valid time (when it was true) and system time (since when we have believed it) per row, for the types you choose. The query does not change; the instant is a setting. See ADR-027.

SET og.valid_at  = '2021-06-01';
SET og.system_at = '2024-01-01';
SELECT og_cypher('kb', $$ MATCH (p:Person {name: "ann"}) RETURN p.salary $$);

The compiled SQL is the same for every instant. A temporal type reads three branches: current rows; open history rows (__sys_to = 'infinity', valid-time slices still believed), visible whenever their validity contains the instant and found through a partial GiST index on __valid; and closed history rows (superseded beliefs), read only when an instant is set. So a query with no instant still probes that partial index once per temporal type. Single hops over temporal relationship types read the edge tables (the same three branches) instead of the adjacency segments — always, not only when an instant is set. With an instant set, these refuse rather than answer from the present: unlabelled node patterns (in a graph with temporal node types), variable-length paths over temporal relationship types, relationship variables without a single type, and TypeQL. An update dated after the end of the current validity raises OG_TEMPORAL_RANGE (22023). Raw SQL writes are versioned by the same trigger.

An update or delete with og.valid_from in the future leaves the value that holds until then in an open history row, so queries with no instant keep seeing it until that date. Not implemented: retention policy, editing past valid-time slices.

Over Bolt, tx_metadata keys valid_at/validAt, system_at/systemAt, valid_from/validFrom and valid_to/validTo become these settings for that transaction (auto-commit RUN included).

Write security — spec 014

Write privileges are PostgreSQL table and column grants on the per-type storage tables, so they hold for raw SQL exactly as for Cypher. The shared registries (og_node, og_edge, og_adj, og_role_player) carry row-level security that lets a role write a registry row only if it could write that type's storage table. Reads of the registries are not restricted. See ADR-026.

Context settings: og.actor, og.source, og.reason, og.request_id reach the audit log (og_data.og_audit); og.actor and og.source also reach stamped rows. The Bolt gateway maps tx_metadata keys actor, source, reason, request_id/requestId to transaction-local settings.

A write-level role without schema privileges that writes an undeclared property now keeps it in __ext instead of failing on og_add_property. Limits: TypeQL action bodies receive no parameters; the audit row of an action names run_as as db_user, not the caller. The action name is cleared on every exit, so a failed action does not leave it on later audit rows.