> For the complete documentation index, see [llms.txt](https://v2.dataos.info/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://v2.dataos.info/references/interfaces/apis/data-product-apis/querying-data-products/advanced/statement-lifecycle.md).

# Statement lifecycle

Detailed sequence diagrams walking through the statement lifecycle, step by step.

This is the visual deep dive into the same async pipeline described in [Query lifecycle](https://v2.dataos.info/references/interfaces/apis/data-product-apis/querying-data-products/advanced/query-lifecycle.md). REST, Semantic SQL, the Metric API, and Source SQL share it; GraphQL usually returns inline data but falls back to it for long-running requests.

For the endpoint reference, request/response shapes, strategy and status tables, fetch formats, staleness handling, and retry semantics, see [Query lifecycle](https://v2.dataos.info/references/interfaces/apis/data-product-apis/querying-data-products/advanced/query-lifecycle.md). This page assumes that reference and focuses on *how the components talk to each other* at each step, as sequence diagrams.

Every async submit returns `202 Accepted` immediately. Poll for status, then fetch the result.

### Standard flow

```mermaid
sequenceDiagram
    autonumber
    participant C as Client
    participant A as API
    participant Q as Queue
    participant W as Worker
    participant S as Object Store

    C->>A: POST /api/v1/query/... {query}
    A-->>C: 202 {id, strategy:"execute", status:"QUEUED", _links}

    loop Poll until terminal status
        C->>A: GET /api/v1/query/statement/{id}
        alt still running
            A-->>C: 200 {status:"QUEUED" | "IN_PROGRESS"}
        end
    end

    Note over Q,W: Worker picks job from queue
    W->>S: Write result (Parquet)
    W->>A: Mark status SUCCESS

    C->>A: GET /api/v1/query/statement/{id}
    A-->>C: 200 {status:"SUCCESS", _links.result}

    C->>A: GET /api/v1/query/statement/{id}/result?format=json
    A->>S: Fetch Parquet
    S-->>A: result bytes
    A-->>C: 200 {cols, rows, types, row_count}
```

### Error path

```mermaid
sequenceDiagram
    autonumber
    participant C as Client
    participant A as API
    participant W as Worker

    C->>A: POST /api/v1/query/... {query}
    A-->>C: 202 {id, strategy:"execute", status:"QUEUED", _links}

    loop Poll
        C->>A: GET /api/v1/query/statement/{id}
        A-->>C: 200 {status:"QUEUED" | "IN_PROGRESS"}
    end

    Note over W: Execution fails
    W->>A: Mark status FAILED + error_message

    C->>A: GET /api/v1/query/statement/{id}
    A-->>C: 200 {status:"FAILED", error:"<reason>"}
    Note over C: Do not fetch /result. No artifact exists for FAILED statements
```

### Deduplication

```mermaid
sequenceDiagram
    autonumber
    participant A as Client A
    participant B as Client B
    participant API as API
    participant W as Worker
    participant S as Object Store

    A->>API: POST /query (fingerprint: abc123)
    API-->>A: 202 {id:"req-1", strategy:"execute"}

    Note over W: Query running...

    B->>API: POST /query (same fingerprint: abc123)
    API-->>B: 202 {id:"req-2", strategy:"AWAIT_PRIMARY", primary_request_id:"req-1"}

    W->>S: Write result
    W->>API: Mark req-1 SUCCESS

    A->>API: GET /statement/req-1
    API-->>A: 200 {status:"SUCCESS"}

    B->>API: GET /statement/req-2
    API-->>B: 200 {status:"SUCCESS"}
    Note over B: Resolves via req-1's result. No duplicate execution.

    rect rgb(230, 245, 230)
        participant CC as Client C
        CC->>API: POST /query (same fingerprint: abc123)
        API-->>CC: 202 {id:"req-3", strategy:"REUSE_RESULT", status:"SUCCESS"}
        Note over CC: Cached: skip polling and go straight to /result
    end
```

*(Strategy and status meanings: see the tables in* [*Query lifecycle*](https://v2.dataos.info/references/interfaces/apis/data-product-apis/querying-data-products/advanced/query-lifecycle.md#2-read-the-execution-strategy)*.)*

### GraphQL timeout path

```mermaid
sequenceDiagram
    participant C as Client
    participant G as GraphQL endpoint
    participant A as Statement API

    C->>G: POST /api/v1/query/semantic/graphql
    G->>A: POST semantic/rest (internal)
    loop Poll up to timeout
        G->>A: GET /statement/{id}
    end
    alt Completed in time
        G-->>C: 200 { data: [...] }
    else Timeout
        G-->>C: 202 Retry-After + extensions.statementId
        C->>A: GET /statement/{id} (poll)
        C->>A: GET /statement/{id}/result
    end
```

### Submit paths

| Submit        | Path                                        |
| ------------- | ------------------------------------------- |
| Source SQL    | `POST /api/v1/query/statement`              |
| Semantic REST | `POST /api/v1/query/semantic/rest`          |
| Semantic SQL  | `POST /api/v1/query/semantic/sql`           |
| Metric API    | `GET` or `POST /api/v1/query/metric/{name}` |
| GraphQL       | `POST /api/v1/query/semantic/graphql`       |

This table adds the GraphQL submit path on top of [Query lifecycle](https://v2.dataos.info/references/interfaces/apis/data-product-apis/querying-data-products/advanced/query-lifecycle.md#1-submit)'s submit table, since GraphQL is the one method with a fallback into this same pipeline.

Poll: `GET /api/v1/query/statement/{id}`. Fetch: `GET /api/v1/query/statement/{id}/result` (`format=json|csv|yaml|parquet`; see [Query lifecycle](https://v2.dataos.info/references/interfaces/apis/data-product-apis/querying-data-products/advanced/query-lifecycle.md#4-fetch) for behavior per format, and [Handle staleness](https://v2.dataos.info/references/interfaces/apis/data-product-apis/querying-data-products/advanced/query-lifecycle.md#handle-staleness) for the `Is-Stale` header).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://v2.dataos.info/references/interfaces/apis/data-product-apis/querying-data-products/advanced/statement-lifecycle.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
