GraphQL Query Patterns

Paginated listings

query ProjectList($page: Int!, $pageSize: Int!) {
  projectList(page: $page, pageSize: $pageSize, orderBy: ["-start_date"]) {
    results {
      id
      name
      startDate
    }
    pageInfo {
      totalCount
      totalPages
    }
  }
}

Nested buckets

query ProjectWithDerivatives($id: Int!) {
  project(id: $id) {
    name
    derivativeList(filter: { maturity_date__gte: "2024-01-01" }) {
      id
      maturityDate
      volume
    }
  }
}

Query a manager relation

For a manager declaration such as owner: User | None and reviewer_list: Bucket[User], generated GraphQL exposes an object field and a paginated relation-list field. Query both fields directly:

query ProjectRelations($projectId: ID!) {
  project(id: $projectId) {
    owner { id name }
    reviewerList(page: 1, pageSize: 20) {
      items { id name }
      pageInfo { totalCount currentPage totalPages pageSize }
    }
  }
}

Nested relation filters use the same resolved manager type. A direct relation uses a nested object, while a collection relation uses any or none:

query ProjectsWithRelatedUsers {
  projectList(filter: {
    owner: { name: "Alice" }
    reviewerList: { any: { name: "Alice" } }
  }) {
    items { id name owner { id name } }
  }
}

For the Python annotation forms and the generated mutation/subscription contracts, see the GraphQL concept guide, the task guide, and the API reference.

Filter a calculation by manager input

For a calculation manager with project = Input(Project), use the same nested direct-relation shape as a persisted manager:

query ProjectCommercials($projectId: ID!) {
  projectCommercialList(filter: {project: {id: $projectId}}) {
    items {
      project { id name }
      targetDate
    }
  }
}

{"projectId": 42}

The generated filter is directly usable with a normal GraphQL request. The server translates project: {id: ...} to the calculation lookup project__id=...; replace id with a supported nested field or lookup when needed. See the calculation how-to and API reference for the declaration and compatibility rules.

Custom mutation with Measurement input

mutation UpdateInventory($id: Int!, $price: MeasurementScalar!) {
  updateInventoryItem(id: $id, price: $price) {
    success
    errors
    inventoryItem {
      id
      price
    }
  }
}

Aggregation via GraphQL property

query ProjectSummary($id: Int!) {
  project(id: $id) {
    name
    totalCapex
    duration
    derivativeSummary
  }
}

Use these patterns as a starting point and adapt filters or selections to your domain.