Skip to main content

Mutations

For Data Analysts

Olytix Core's GraphQL API provides mutation operations for managing caches, pre-aggregations, and project state.

Cache Management​

Invalidate Cube Cache​

Invalidate all cached query results for a specific cube. Use this after data updates to ensure fresh results.

mutation {
  invalidateCache(cube: "orders")
}

Response:

{
  "data": {
    "invalidateCache": true
  }
}

Use Cases:

  • After loading new data into the warehouse
  • When cube definitions have changed
  • To force recalculation of cached aggregations

Example with Variables:

mutation InvalidateOrdersCache($cubeName: String!) {
  invalidateCache(cube: $cubeName)
}

Variables:

{
  "cubeName": "orders"
}

Pre-aggregation Management​

Refresh Pre-aggregation​

Trigger an immediate refresh of a pre-aggregation table. This is useful when you need fresh aggregated data outside the normal refresh schedule.

mutation {
  refreshPreAggregation(
    cube: "orders"
    preAggregation: "orders_by_region_daily"
  ) {
    success
    message
    jobId
  }
}

Response:

{
  "data": {
    "refreshPreAggregation": {
      "success": true,
      "message": "Pre-aggregation refresh triggered successfully",
      "jobId": "preagg_refresh_abc123"
    }
  }
}

Use Cases:

  • After significant data loads
  • When data corrections have been applied
  • Before generating critical reports

Error Response:

{
  "data": {
    "refreshPreAggregation": {
      "success": false,
      "message": "Pre-aggregation 'invalid_preagg' not found in cube 'orders'",
      "jobId": null
    }
  }
}

Refresh Multiple Pre-aggregations​

Use aliases to refresh multiple pre-aggregations in a single request.

mutation RefreshAllOrdersPreaggs {
  daily: refreshPreAggregation(
    cube: "orders"
    preAggregation: "orders_by_region_daily"
  ) {
    success
    jobId
  }
  weekly: refreshPreAggregation(
    cube: "orders"
    preAggregation: "orders_by_region_weekly"
  ) {
    success
    jobId
  }
  monthly: refreshPreAggregation(
    cube: "orders"
    preAggregation: "orders_by_region_monthly"
  ) {
    success
    jobId
  }
}

Response:

{
  "data": {
    "daily": {
      "success": true,
      "jobId": "preagg_refresh_abc123"
    },
    "weekly": {
      "success": true,
      "jobId": "preagg_refresh_def456"
    },
    "monthly": {
      "success": true,
      "jobId": "preagg_refresh_ghi789"
    }
  }
}

Subscriptions​

Olytix Core also provides real-time subscriptions for monitoring long-running operations.

Subscribe to Query Updates​

Monitor updates for a long-running or periodic query.

subscription {
  queryUpdates(queryId: "query_abc123") {
    data
    meta {
      executionTimeMs
      fromCache
    }
  }
}

Subscribe to Pre-aggregation Status​

Monitor the build status of pre-aggregations for a cube.

subscription {
  preAggregationStatus(cube: "orders") {
    name
    status
    lastRefreshAt
    nextRefreshAt
    rowCount
    sizeBytes
  }
}

Status Values:

StatusDescription
NOT_BUILTPre-aggregation has never been built
BUILDINGBuild is currently in progress
FRESHPre-aggregation is up to date
STALEPre-aggregation needs refresh
FAILEDLast build attempt failed

Example Output:

{
  "data": {
    "preAggregationStatus": {
      "name": "orders_by_region_daily",
      "status": "BUILDING",
      "lastRefreshAt": "2024-01-20T08:00:00Z",
      "nextRefreshAt": "2024-01-21T08:00:00Z",
      "rowCount": null,
      "sizeBytes": null
    }
  }
}

Combining Mutations with Queries​

You can combine mutations with queries in a single request to perform an action and retrieve updated state.

mutation InvalidateAndVerify {
  invalidateCache(cube: "orders")
}

query VerifyCacheStatus {
  cube(name: "orders") {
    name
    measures {
      name
    }
  }
}

Error Handling​

Mutation errors follow standard GraphQL error conventions:

{
  "data": {
    "refreshPreAggregation": null
  },
  "errors": [
    {
      "message": "Pre-aggregation service not available",
      "locations": [{ "line": 2, "column": 3 }],
      "path": ["refreshPreAggregation"],
      "extensions": {
        "code": "SERVICE_UNAVAILABLE"
      }
    }
  ]
}

Common Error Codes​

CodeDescription
CUBE_NOT_FOUNDThe specified cube does not exist
PREAGG_NOT_FOUNDThe specified pre-aggregation does not exist
SERVICE_UNAVAILABLERequired service is not available
PERMISSION_DENIEDUser lacks permission for this operation
RATE_LIMITEDToo many requests, try again later

Best Practices​

Cache Invalidation​

  1. Be specific: Invalidate only the cubes that have changed data
  2. Schedule during low traffic: Run cache invalidations during off-peak hours when possible
  3. Monitor after invalidation: Expect slightly higher query latency immediately after cache invalidation

Pre-aggregation Refresh​

  1. Track job IDs: Store returned job IDs to monitor refresh progress via subscriptions
  2. Avoid overlapping refreshes: Check if a refresh is already in progress before triggering another
  3. Handle failures gracefully: Implement retry logic for failed refreshes
# Check status before triggering refresh
query CheckStatus {
  cube(name: "orders") {
    name
  }
}

# Then trigger refresh if needed
mutation ConditionalRefresh {
  refreshPreAggregation(
    cube: "orders"
    preAggregation: "orders_by_region_daily"
  ) {
    success
    jobId
    message
  }
}

Next Steps​