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 changes and changes to users, roles, sessions, and remote credentials share one transaction. Commands run in order; a command failure rolls back their database changes together. For example, CreateRole can be followed by CreateUser in the same query to assign the new role to the new user.

Two ordering rules need special care:

  • Authenticate and RefreshToken must each be submitted alone. Use the returned tokens for subsequent requests.

  • Creating or changing a remote credential affects media reads in later queries. To use the new key, submit the credential change separately and wait for success before requesting media, even if you could put the change first in a combined query.

All commands in a query run with the permissions that allowed the query to begin. Changing a user or role within the query does not grant or remove permission for its later commands. See Access Control for session revocation and Remote credentials for credential changes during requests and batching.

A failure while fetching requested media or delivering the response can occur after database changes have been saved. An error response or lost connection therefore does not always mean that the writes were rolled back. Reconnect and inspect the affected data before retrying a write with an uncertain outcome. Use stable application IDs and conditional adds to prevent duplicates; request references cannot prevent duplicate writes across retries.

Responses explains recovery for different failures. API Description covers request structure and binary ordering. Reading results covers result selection.