What are instances
Instances are the concrete data that populates your containers and views. Each instance conforms to the schema of its container. When you write data through a view, you create or update instances. When you query a view, you read instances.Nodes and edges
Nodes are instances that represent entities. Edges are instances that connect two nodes and represent relationships. Together, nodes and edges form a graph structure that you can traverse and analyze. Both are stored in containers and exposed through views.Edges reference source and target nodes by their instance IDs. You can query edges by property, by node reference, or by graph traversal patterns.
Querying instances
You can query instances using filters, search, and aggregation. Filter expressions allow you to narrow results by property values. Search supports full-text and semantic queries. Aggregation lets you compute counts, sums, and other statistics over instances.Create, patch, and replace
POST /models/instances creates, patches, replaces, and deletes nodes and edges in one transaction. One request accepts at most 1000 nodes and edges. Direct relations in that request can reference at most 30000 distinct nodes. The response returns instances in the same order as the request.
When no node or edge has that externalId in the space, the operation creates it and writes the properties in sources. An edge can also create its start or end node when autoCreateStartNodes or autoCreateEndNodes is set. A direct relation can create its target when autoCreateDirectRelations is set.
When the instance already exists, the properties you name are updated and the others stay as they are. Set replace to true to replace every property on the containers behind the sources you send. An omitted property becomes the container default, or null when the container defines no default. The request fails when a required property is missing. A patch that changes nothing leaves lastUpdatedTime unchanged.
You can also pass instances in delete. Creates, updates, and deletes in the same request run together, and the combined count cannot exceed 1000. A delete of an instance that is already gone is skipped.
The caller needs dataModelsAcl:WRITE on the views and containers being written. For the ingest model, see Ingest instances.
Delete instances
POST /models/instances/delete removes up to 1000 nodes and edges in one transaction. Deleting a node also deletes the edges that start or end on that node. When a node has too many edges for one request, delete those edges first. Identifiers that are already gone are ignored. A delete in a space that does not exist is rejected.
Sync
POST /models/instances/sync returns changes for nodes and edges that match a filter. Every response includes a nextCursor. The filter uses the same query language as the query operation, and sorting is not supported. See Query features.
Key capabilities
- Create and update — Insert or upsert nodes and edges through views.
- Delete — Remove instances when they are no longer needed.
- List and filter — List instances with optional filters on properties.
- Search — Search instances by text or semantic similarity.
- Aggregate — Compute aggregations over instances.
- Sync — Read changes that match a filter. See Sync.