SchemaService
Schema management operations.
Proto source
Transport
All methods are available via:
- gRPC on port 7080 — native high-performance API
- REST/JSON on port 7081 — HTTP/JSON transcoding via embedded structured-proxy
Methods
CreateLabel
Create a new node label with property definitions.
HTTP: POST /v1/graph/schema/labels
Request: CreateLabelRequest
| Field | Type | Description |
|---|---|---|
name | string | Label name (e.g., "User", "Movie", "Memory"). |
properties | PropertyDefinition[] | Regular property declarations. Defines types, constraints (unique, required). |
computed_properties | ComputedPropertyDefinition[] | COMPUTED property specifications. The TtlReaper background worker picks up TTL specs automatically; DECAY and VECTOR_DECAY are evaluated at query time. These are stored in the label schema and apply to all nodes of this label. |
schema_mode | SchemaMode | Schema mode controlling validation and interning. Defaults to STRICT when unspecified. Use FLEXIBLE to replicate schema-free behaviour on a declared label; use VALIDATED to accept extra properties in an overflow map. |
Response: Label
| Field | Type | Description |
|---|---|---|
name | string | — |
properties | PropertyDefinition[] | Regular (non-computed) property definitions. |
schema_revision | uint64 | Schema revision (DDL snapshot identity). Advances on ALTER operations that change write-path semantics (placement, shard_keys, mode). Distinct from data-side versioning (MVCC commit_ts, future per-row OCC _v) — "revision" is reserved for DDL identity per ADR-023. |
computed_properties | ComputedPropertyDefinition[] | COMPUTED property specifications declared for this label. |
schema_mode | SchemaMode | Validation and interning mode for this label. STRICT by default. |
CreateEdgeType
Create a new edge type with property definitions.
HTTP: POST /v1/graph/schema/edge-types
Request: CreateEdgeTypeRequest
| Field | Type | Description |
|---|---|---|
name | string | — |
properties | PropertyDefinition[] | — |
Response: EdgeType
| Field | Type | Description |
|---|---|---|
name | string | — |
properties | PropertyDefinition[] | — |
schema_revision | uint64 | Schema revision (DDL snapshot identity). See Label.schema_revision. |
ListLabels
List all labels in the schema.
HTTP: GET /v1/graph/schema/labels
Request: ListLabelsRequest
Empty request (no fields).
Response: ListLabelsResponse
| Field | Type | Description |
|---|---|---|
labels | Label[] | — |
ListEdgeTypes
List all edge types in the schema.
HTTP: GET /v1/graph/schema/edge-types
Request: ListEdgeTypesRequest
Empty request (no fields).
Response: ListEdgeTypesResponse
| Field | Type | Description |
|---|---|---|
edge_types | EdgeType[] | — |
Types
ComputedPropertyDefinition
A COMPUTED property specification within a CreateLabelRequest. COMPUTED properties are evaluated at query time from node data — no value is stored per node. The spec is stored once in the label schema and applied to all nodes of that label during MATCH/RETURN execution. Three types: TTL — background auto-delete after duration_secs DECAY — float value interpolated between initial and target over time VECTOR_DECAY — query-time multiplier on vector similarity scores
| Field | Type | Description |
|---|---|---|
name | string | Property name. Must not collide with regular PropertyDefinition names in the same label. Convention: prefix TTL properties with underscore (e.g., "_ttl", "_expires"). |
computed_type | ComputedType | Kind of computed property. Required. |
formula_type | DecayFormulaType | Decay formula variant. Required for DECAY and VECTOR_DECAY types. Ignored for TTL type. |
lambda | double | For EXPONENTIAL formula: pre-computed λ = ln(2) / half_life_fraction. Example: half-life at 50% of duration → lambda = ln(2) / 0.5 ≈ 1.386. |
tau | double | For POWER_LAW formula: time scale as fraction of duration (τ > 0). Controls how fast the initial decay is. Smaller τ → faster initial drop. |
alpha | double | For POWER_LAW formula: decay exponent (α > 0). Larger α → faster decay overall. |
initial | double | Starting value at elapsed = 0 (for DECAY type only). Default: 1.0 (full strength at creation). |
target | double | Target value at elapsed ≥ duration_secs (for DECAY type only). Default: 0.0 (fully decayed at end of duration). |
duration_secs | uint64 | Duration in seconds: decay occurs over [0, duration_secs]; TTL expires after this. Required for all computed types. |
anchor_field | string | Name of the TIMESTAMP property to measure elapsed time from. Must be declared as a regular TIMESTAMP property in the same CreateLabelRequest. Example: "created_at", "indexed_at", "expires_at". |
scope | TtlScopeType | What to delete when a TTL expires (for TTL type only). Default (UNSPECIFIED): treated as TTL_SCOPE_TYPE_NODE — delete the whole node. |
target_field | string | For TTL_SCOPE_TYPE_SUBTREE: the DOCUMENT property to delete on expiry. The anchor_field timestamp is preserved; only this DOCUMENT property is removed. Leave empty if scope is FIELD or NODE (ignored in those cases). |
CreateEdgeTypeRequest
| Field | Type | Description |
|---|---|---|
name | string | — |
properties | PropertyDefinition[] | — |
CreateLabelRequest
| Field | Type | Description |
|---|---|---|
name | string | Label name (e.g., "User", "Movie", "Memory"). |
properties | PropertyDefinition[] | Regular property declarations. Defines types, constraints (unique, required). |
computed_properties | ComputedPropertyDefinition[] | COMPUTED property specifications. The TtlReaper background worker picks up TTL specs automatically; DECAY and VECTOR_DECAY are evaluated at query time. These are stored in the label schema and apply to all nodes of this label. |
schema_mode | SchemaMode | Schema mode controlling validation and interning. Defaults to STRICT when unspecified. Use FLEXIBLE to replicate schema-free behaviour on a declared label; use VALIDATED to accept extra properties in an overflow map. |
EdgeType
An edge type definition.
| Field | Type | Description |
|---|---|---|
name | string | — |
properties | PropertyDefinition[] | — |
schema_revision | uint64 | Schema revision (DDL snapshot identity). See Label.schema_revision. |
Label
A node label definition returned by CreateLabel and ListLabels.
| Field | Type | Description |
|---|---|---|
name | string | — |
properties | PropertyDefinition[] | Regular (non-computed) property definitions. |
schema_revision | uint64 | Schema revision (DDL snapshot identity). Advances on ALTER operations that change write-path semantics (placement, shard_keys, mode). Distinct from data-side versioning (MVCC commit_ts, future per-row OCC _v) — "revision" is reserved for DDL identity per ADR-023. |
computed_properties | ComputedPropertyDefinition[] | COMPUTED property specifications declared for this label. |
schema_mode | SchemaMode | Validation and interning mode for this label. STRICT by default. |
ListEdgeTypesRequest
No fields.
ListEdgeTypesResponse
| Field | Type | Description |
|---|---|---|
edge_types | EdgeType[] | — |
ListLabelsRequest
No fields.
ListLabelsResponse
| Field | Type | Description |
|---|---|---|
labels | Label[] | — |
PropertyDefinition
A property definition within a label or edge type.
| Field | Type | Description |
|---|---|---|
name | string | Property name. |
type | PropertyType | Declared type. COMPUTED properties are represented separately via ComputedPropertyDefinition; use PropertyType for regular properties only. |
required | bool | Whether this property is required (NOT NULL). Writes missing this property are rejected in STRICT and VALIDATED schema modes. |
unique | bool | Whether a UNIQUE B-tree index is maintained for this property. Duplicate values across nodes of this label are rejected. |
Enums
ComputedType
The kind of COMPUTED property.
| Value | Number | Description |
|---|---|---|
COMPUTED_TYPE_UNSPECIFIED | 0 | Unspecified — invalid, rejected by server. |
COMPUTED_TYPE_TTL | 1 | timestamp is older than duration_secs. |
COMPUTED_TYPE_DECAY | 2 | Evaluated inline at query time: value = initial + (target - initial) × formula(elapsed). |
COMPUTED_TYPE_VECTOR_DECAY | 3 | vector_similarity() results. |
DecayFormulaType
Decay formula variant for DECAY and VECTOR_DECAY computed types. All formulas map normalized time t ∈ [0, 1] to weight ∈ [0, 1].
| Value | Number | Description |
|---|---|---|
DECAY_FORMULA_TYPE_UNSPECIFIED | 0 | — |
DECAY_FORMULA_TYPE_LINEAR | 1 | f(t) = max(0, 1 - t). Constant rate, hard cutoff at duration. |
DECAY_FORMULA_TYPE_EXPONENTIAL | 2 | λ = ln(2) / half_life_fraction; pre-computed by client from desired half-life. |
DECAY_FORMULA_TYPE_POWER_LAW | 3 | Recent items decay fast; residual value persists longer than exponential. |
DECAY_FORMULA_TYPE_STEP | 4 | Semantically equivalent to TTL but evaluated at query time (no background delete). |
PropertyType
| Value | Number | Description |
|---|---|---|
PROPERTY_TYPE_UNSPECIFIED | 0 | — |
PROPERTY_TYPE_INT64 | 1 | — |
PROPERTY_TYPE_FLOAT64 | 2 | — |
PROPERTY_TYPE_STRING | 3 | — |
PROPERTY_TYPE_BOOL | 4 | — |
PROPERTY_TYPE_BYTES | 5 | — |
PROPERTY_TYPE_TIMESTAMP | 6 | — |
PROPERTY_TYPE_VECTOR | 7 | — |
PROPERTY_TYPE_LIST | 8 | — |
PROPERTY_TYPE_MAP | 9 | — |
SchemaMode
Schema validation and flexibility mode for a node label. Controls how the write path handles properties at CREATE and SET time. Applied per label via CreateLabelRequest.schema_mode.
| Value | Number | Description |
|---|---|---|
SCHEMA_MODE_UNSPECIFIED | 0 | Unspecified — defaults to STRICT on the server. |
SCHEMA_MODE_STRICT | 1 | interning is applied (up to 80% key storage reduction). |
SCHEMA_MODE_VALIDATED | 2 | +10–20% storage overhead for undeclared properties. |
SCHEMA_MODE_FLEXIBLE | 3 | schema-free default behaviour on labels without a declared schema. |
TtlScopeType
What to delete when a TTL COMPUTED property expires.
| Value | Number | Description |
|---|---|---|
TTL_SCOPE_TYPE_UNSPECIFIED | 0 | — |
TTL_SCOPE_TYPE_FIELD | 1 | Delete only the anchor_field property from the node. Node remains alive. |
TTL_SCOPE_TYPE_SUBTREE | 2 | target_field to be set in ComputedPropertyDefinition. |
TTL_SCOPE_TYPE_NODE | 3 | Delete the entire node and all its outgoing/incoming edges (DETACH DELETE). |