Skip to main content

Transactions and references

A request contains an ordered array of commands. References let a later command use objects selected or created earlier in that request, without sending their identifiers back to the client first. They also avoid fetching properties that the application does not need.

Objects and connections in one request​

This complete request creates a person, a project, and a graph connection from the person to the project. It requires permission to add the entities and connection. Running it again creates another pair of entities.

[
    {"AddEntity": {
        "class": "Person", "_ref": 1,
        "properties": {"name": "Ada"}
    }},
    {"AddEntity": {
        "class": "Project", "_ref": 2,
        "properties": {"name": "Archive"}
    }},
    {"AddConnection": {
        "class": "WorksOn", "src": 1, "dst": 2
    }}
]

_ref assigns a request-local reference. The consuming command uses the field appropriate to its operation: src and dst above, ref in a connection filter, or video_ref for a video operation. A reference can denote a set of matched objects. It is not a persisted object identifier and cannot be reused in the next request. See _ref and ref for field rules.

Finding connected objects​

A reference can also connect two searches. In the graph above, this query finds Ada and then retrieves the projects connected to her:

[
    {"FindEntity": {
        "with_class": "Person", "_ref": 1,
        "constraints": ["$name", "==", "Ada"]
    }},
    {"FindEntity": {
        "with_class": "Project",
        "is_connected_to": {
            "ref": 1, "connection_class": "WorksOn", "direction": "out"
        },
        "results": {"list": ["name"]}
    }}
]

The first command establishes a reference without requesting properties. Its returned: 0 describes the omitted payload; it does not mean Ada was absent. The second command requests project names. results.count returns the number of matches independently of the requested properties.

Transaction boundaries and failures​

Graph mutations run within a graph transaction, but the whole request is not a general transaction across every subsystem. Authentication and user management, remote storage access, and response construction have their own execution phases. In particular, a failure while constructing a response can occur after graph changes have committed. A failed response alone does not prove rollback.

Responses describes the error formats and the state that may have changed at each stage of a request. Inspect the reported error and verify persisted state before retrying a write whose outcome is uncertain. Separate account administration from data ingestion when the application needs to recover them independently. Use stable application IDs and conditional adds where appropriate; a request-local reference cannot prevent duplicate writes across retries.

API Description covers request structure and binary input ordering. Reading results explains property selection and pagination.