Reference

Management mutations and queries

Package Trax.Api.GraphQL.PersistedOperationsSurface GraphQL schemaSource PersistedOperationMutations.cs, PersistedOperationQueries.cs, PersistedOperationsBuilder.Management.cs

UsePersistedOperations registers six fields on the schema for browsing and editing persisted operations, all under a persistedOperations namespace at the root of the query and mutation types, resolved by PersistedOperationQueries and PersistedOperationMutations. Every field calls IPersistedOperationsService, the same service the Trax dashboard's persisted-operations pages call, so both accept and refuse the same things.

query { persistedOperations { persistedOperations(take: 10) { totalCount } } }
mutation { persistedOperations { uploadPersistedOperation(input: { ... }) { success } } }

The management gate

The fields are served only once the host declares who may use them, and each persistedOperations field carries that gate as @authorize:

services.AddTraxGraphQL(graphql => graphql
    .UsePersistedOperations(po => po
        .SingleNode()
        .GateManagement(roles: "Deployer")
    )
);
CallWho gets in
GateManagement(policy: "...")Authenticated callers the ASP.NET Core policy admits. The policy must be registered, or the host fails at startup.
GateManagement(roles: "A,B")Callers holding at least one of the roles.
Repeated GateManagement(...) callsCallers meeting every one of them.
GateManagementToAuthenticatedUsers()Any authenticated caller. On a host with public sign-up that is anyone.
noneNobody: the fields are not in the schema, and the operations console shows no management pages.

The operations console's persisted-operations pages call these fields, so the console and any other GraphQL caller are refused by the same gate. Every gate requires an authenticated caller, whichever of its identities is authenticated, even when a policy alone would admit one that is not.

The gate is not the operations gate. GateOperations and GateOperationsToAuthenticatedUsers govern operations; GateManagement governs persistedOperations. A deploy pipeline that uploads documents holds the management role and reaches nothing under operations, and an operator who manages documents in the operations console holds both. RequireAuthorization() on the builder still gates the whole endpoint, these fields included.

These fields always bypass persisted-operation enforcement (PersistedOperationEnforcementMiddleware, in the HotChocolate execution pipeline), since a client cannot send them by an id it has not uploaded yet. A document is admitted inline only when every operation in it selects nothing at the root but persistedOperations; mixing in another field sends it through enforcement like any other document. A host that declares no management gate serves none of these fields and gets no bypass.

Mutations

uploadPersistedOperation

Insert or update an operation. Runs schema validation, requires exactly one operation in the document, then runs the shape-diff guardrail.

Input fieldTypeRequiredNotes
idString!yesBuild-time-stable identifier. Opaque string, no parse rule; the samples use <name>_v<N>.
documentString!yesThe GraphQL document the id resolves to.
descriptionStringnoOperator-facing note recorded on the row.
bypassShapeDiffBooleannoWhen true, allows an edit that changes the response shape. Default false.
versionIntnoOperator-controlled metadata stored on the row. Not used for routing. Default 0.
tenantKeyStringnoTenant scope. Null targets the single-tenant row set.

Payload: { success, operation, errors[] }.

deactivatePersistedOperation

Soft-delete; subsequent requests for the id resolve to null. The reason is required and recorded in the audit log. Deactivating an operation that is already deactivated succeeds, records the new reason, and sends the change to every node again.

Input fieldTypeRequired
idString!yes
reasonString!yes
tenantKeyStringno

restorePersistedOperation

Reactivate a deactivated row.

Input fieldTypeRequired
idString!yes
tenantKeyStringno

Queries

persistedOperations(filter, take, skip)

Paginated list, newest-updated first.

Filter fieldTypeNotes
isActiveBooleanWhen set, restricts to active or deactivated rows.
tenantKeyStringTenant scope.
idStartsWithStringPrefix filter on the id.

Defaults: take is 50 when not given, zero or negative, or over 200 (a take of 500 returns 50 rows, not 200); skip is floored at 0.

persistedOperation(id, tenantKey)

Look up a single row. Returns null when missing.

persistedOperationHistory(id, tenantKey, take, skip)

Audit history for an operation, most-recent first. Same take / skip defaults as persistedOperations.

Reserved ids

Ids starting with trax_machine_, trax_progress_, trax_view_, trax_client_ or trax_console_ belong to the documents the host registers itself (generated documents), and trax_train_ to the train documents an earlier version generated. Upload, deactivate and restore refuse them with the code RESERVED_ID, and IPersistedOperationStore's UpsertAsync, DeactivateAsync and RestoreAsync throw PersistedOperationInputException.

Error payload

All mutations return errors via the payload errors[] array; mutations never throw to the client. Each entry has:

FieldTypeNotes
codeString!Stable code: PARSE_FAILED, SCHEMA_VALIDATION_FAILED, SHAPE_DIFF_VIOLATION, NOT_FOUND, INVALID_INPUT (an empty required field, or a document with other than one operation), RESERVED_ID (an id under a reserved prefix, see Reserved ids), CHANGE_NOT_BROADCAST (the change is saved, but the broker did not confirm its broadcast).
messageString!Human-readable message. On SHAPE_DIFF_VIOLATION it says to upload again with bypassShapeDiff: true if the change is shape-safe.
locations[Location!]1-based line / column. Present on parse errors and most schema-validation errors.
path[String!]Response path. Present on some schema-validation errors.
oldFingerprintStringPresent only on SHAPE_DIFF_VIOLATION.
newFingerprintStringPresent only on SHAPE_DIFF_VIOLATION.

CHANGE_NOT_BROADCAST is the one error that comes with an operation: the change was saved and is in force on the node that made it, so the payload carries the saved row, and success is false because the other nodes were not told. They pick the change up when their cached entry reaches its maximum age (WithCacheMaxAge, five minutes by default). Repeating the change sends it again.

See PersistedOperationException for the underlying exception types and how the codes map, and Error Codes for every code the endpoint returns.

Example

mutation Upload($input: UploadPersistedOperationInput!) {
  persistedOperations {
    uploadPersistedOperation(input: $input) {
      success
      operation { id shapeFingerprint isActive }
      errors {
        code
        message
        locations { line column }
        oldFingerprint
        newFingerprint
      }
    }
  }
}
{
  "input": {
    "id": "userProfile_v1",
    "document": "query UserProfile($id: Int!) { user(id: $id) { id name email } }"
  }
}

See also