GraphQL API Overview

Data Index provides a GraphQL API for querying workflow instances and task executions.

Accessing the API

GraphQL Endpoint

POST http://data-index-service:8080/graphql
Content-Type: application/json

{
  "query": "{ ... }"
}

GraphQL UI (Development)

For interactive exploration:

http://data-index-service:8080/graphql-ui

Schema Overview

WorkflowInstance

Represents a workflow execution instance.

type WorkflowInstance {
  id: ID!
  name: String!
  namespace: String
  version: String
  status: WorkflowInstanceStatus!
  startDate: String
  endDate: String
  lastUpdate: String
  inputData: String      # JSON as string
  outputData: String     # JSON as string
  taskExecutions: [TaskExecution!]!
  error: WorkflowInstanceError
}

enum WorkflowInstanceStatus {
  RUNNING
  COMPLETED
  FAULTED
  CANCELLED
  SUSPENDED
}

type WorkflowInstanceError {
  type: String
  title: String
  detail: String
  status: Int
  instance: String
}

Field descriptions:

  • id - Unique workflow instance identifier (from Quarkus Flow)

  • name - Workflow name

  • namespace - Workflow namespace (optional)

  • version - Workflow version

  • status - Current instance status

  • startDate - ISO 8601 timestamp when instance started

  • endDate - ISO 8601 timestamp when instance ended (completed/faulted)

  • lastUpdate - ISO 8601 timestamp of last status change

  • inputData - Workflow input as JSON string

  • outputData - Workflow output as JSON string

  • taskExecutions - List of task executions within this instance

  • error - Error details if status is FAULTED

TaskExecution

Represents a task execution within a workflow instance.

type TaskExecution {
  id: ID!
  taskName: String!
  taskPosition: String!
  status: String!
  startDate: String
  endDate: String
  error: Error            # Structured error details
  inputData: String       # JSON as string
  outputData: String      # JSON as string
}

type Error {
  type: String
  title: String
  detail: String
  status: Int
  instance: String
}

Field descriptions:

  • id - Unique task execution identifier (derived from instanceId:taskPosition)

  • taskName - Name of the task (optional)

  • taskPosition - JSONPointer identifying task location in workflow (e.g., "/do/0", "/do/1/then/0")

  • status - Task status: RUNNING, COMPLETED, FAULTED

  • startDate - ISO 8601 timestamp when task started

  • endDate - ISO 8601 timestamp when task ended

  • error - Structured error details if status is FAULTED (same Error type as WorkflowInstance)

  • inputData - Task input as JSON string

  • outputData - Task output as JSON string

Why String for JSON fields?

Input/output data is returned as JSON-encoded strings. Clients must parse the JSON themselves. This is a pragmatic solution - custom GraphQL scalars for JSON are complex with SmallRye GraphQL.

Queries

Get All Workflow Instances

Retrieve all workflow instances (with optional limit):

{
  getWorkflowInstances(limit: 10) {
    id
    name
    namespace
    status
    startDate
    endDate
    taskExecutions {
      taskName
      taskPosition
      status
    }
  }
}

Get Workflow Instance by ID

Retrieve a specific workflow instance:

{
  getWorkflowInstance(id: "01KQ7KGYQYHSG58PBSKTC2Y07Q") {
    id
    name
    status
    inputData
    outputData
    taskExecutions {
      taskName
      status
      inputData
      outputData
    }
  }
}

Filter Workflow Instances

Filter by status, name, namespace:

{
  getWorkflowInstances(
    filter: {
      status: COMPLETED
      name: "petstore"
    }
  ) {
    id
    name
    version
    status
    startDate
    endDate
    lastUpdate
  }
}

Get Failed Workflows with Error Details

Retrieve failed workflows with complete error information:

{
  getWorkflowInstances(filter: { status: FAULTED }) {
    id
    name
    status
    startDate
    endDate
    error {
      type
      title
      detail
      status
      instance
    }
    taskExecutions {
      taskPosition
      taskName
      status
      error {
        type
        title
        status
        instance
      }
    }
  }
}

Query Examples

Example 1: List Recent Completions

curl -s http://localhost:8080/graphql \
  -H "Content-Type: application/json" \
  -d '{
    "query": "{ getWorkflowInstances(limit: 5) { id name status endDate } }"
  }' | jq .

Response:

{
  "data": {
    "getWorkflowInstances": [
      {
        "id": "01KQ7KGYQYHSG58PBSKTC2Y07Q",
        "name": "simple-set",
        "status": "COMPLETED",
        "endDate": "2026-04-27T18:55:29.065Z"
      }
    ]
  }
}

Example 2: Get Workflow with Task Details

curl -s http://localhost:8080/graphql \
  -H "Content-Type: application/json" \
  -d '{
    "query": "{ getWorkflowInstance(id: \"01KQ7KGYQYHSG58PBSKTC2Y07Q\") { id name status taskExecutions { taskPosition status startDate endDate } } }"
  }' | jq .

Response:

{
  "data": {
    "getWorkflowInstance": {
      "id": "01KQ7KGYQYHSG58PBSKTC2Y07Q",
      "name": "simple-set",
      "status": "COMPLETED",
      "taskExecutions": [
        {
          "taskPosition": "do/0/set-0",
          "status": "COMPLETED",
          "startDate": "2026-04-27T18:55:29.057Z",
          "endDate": "2026-04-27T18:55:29.061Z"
        },
        {
          "taskPosition": "do/1/set-1",
          "status": "COMPLETED",
          "startDate": "2026-04-27T18:55:29.061Z",
          "endDate": "2026-04-27T18:55:29.065Z"
        }
      ]
    }
  }
}

Example 3: Parse JSON Input/Output

curl -s http://localhost:8080/graphql \
  -H "Content-Type: application/json" \
  -d '{
    "query": "{ getWorkflowInstance(id: \"01KQ7KGYQYHSG58PBSKTC2Y07Q\") { inputData outputData } }"
  }' | jq -r '.data.getWorkflowInstance | {input: (.inputData | fromjson), output: (.outputData | fromjson)}'

Response:

{
  "input": {
    "name": "E2E Test"
  },
  "output": {
    "completed": true,
    "mode": "PostgreSQL"
  }
}

Filtering and Sorting

The GraphQL API supports comprehensive filtering and sorting capabilities.

Workflow Instance Filters

  • status: Filter by workflow status (RUNNING, COMPLETED, FAULTED, CANCELLED, SUSPENDED)

  • name: String filters (eq, like, in)

  • namespace: String filters (eq, like, in)

  • version: String filters (eq, like, in)

  • startTime/endTime: DateTime filters (eq, gt, gte, lt, lte, between)

  • input/output: JSON path filtering (filter by nested JSON fields)

  • error: Filter by error type, status, title, detail, instance

Task Execution Filters

  • taskPosition: String filters (eq, like, in) - filters by task location in workflow

  • taskName: String filters (eq, like, in)

  • status: String filters (eq, in)

  • enter/exit: DateTime filters (maps to start/end times) - filter by task execution time

  • inputArgs/outputArgs: JSON path filtering (filter by task input/output data)

  • error: Filter by error details

Field Name Mappings:

GraphQL uses backward-compatible field names that map to entity fields internally:

  • enter → entity start field (task start time)

  • exit → entity end field (task end time)

  • inputArgs → entity input field

  • outputArgs → entity output field

  • taskPosition → composite key field id.taskPosition

These mappings are transparent to API consumers.

Sorting

Both workflows and tasks support ordering by most fields:

{
  getTaskExecutions(
    orderBy: { enter: DESC }  # Order by start time, newest first
  ) {
    taskPosition
    taskName
    startDate
  }
}

Supported sort fields:

  • Workflows: id, name, namespace, version, status, startTime, endTime, lastUpdate

  • Tasks: id, taskName, taskPosition, enter (start), exit (end)

Filter Examples

Filter by time range:

{
  getWorkflowInstances(
    filter: {
      startTime: { gte: "2026-01-01T00:00:00Z", lt: "2026-02-01T00:00:00Z" }
      status: { eq: COMPLETED }
    }
  ) {
    id
    name
    startDate
  }
}

Filter by JSON field:

{
  getTaskExecutions(
    filter: {
      inputArgs: {
        eq: [{ key: "customerId", value: "customer-123" }]
      }
    }
  ) {
    taskName
    inputData
  }
}

Filter by task position:

{
  getTaskExecutions(
    filter: { taskPosition: { eq: "/do/0" } }
  ) {
    id
    taskPosition
    taskName
    status
  }
}

Order by completion time:

{
  getTaskExecutions(
    orderBy: { exit: ASC }  # Completed tasks, earliest first
  ) {
    taskName
    endDate
    status
  }
}

Error Handling

GraphQL errors are returned in the errors field:

{
  "errors": [
    {
      "message": "Workflow instance not found: invalid-id",
      "locations": [...],
      "path": ["getWorkflowInstance"]
    }
  ]
}

Next Steps