> 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/concepts/foundations/activation/apis/getting-started/querying-data-products/statement-lifecycle.md).

# Statement lifecycle

REST, Semantic SQL, the Metric API, and Source SQL share one async execution pipeline. GraphQL usually returns inline data, but long-running requests fall back to the same statement flow.

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, go straight to /result
    end
```

| `strategy`      | Meaning                         | What to do                                |
| --------------- | ------------------------------- | ----------------------------------------- |
| `EXECUTE`       | Fresh execution queued          | Poll until `SUCCESS` or `FAILED`          |
| `REUSE_RESULT`  | Identical cached result         | `status` is already `SUCCESS` — fetch now |
| `AWAIT_PRIMARY` | Identical query already running | Poll normally; shares primary result      |

| Status        | Meaning                     |
| ------------- | --------------------------- |
| `ACCEPTED`    | Received, not yet queued    |
| `QUEUED`      | In the execution queue      |
| `IN_PROGRESS` | Worker executing            |
| `SUCCESS`     | Complete — result available |
| `FAILED`      | Failed — see `error` field  |

### 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
```

### Fetching results

```bash
GET /api/v1/query/statement/{id}/result?format=json   # default
GET /api/v1/query/statement/{id}/result?format=csv
GET /api/v1/query/statement/{id}/result?format=yaml
GET /api/v1/query/statement/{id}/result?format=parquet  # 307 redirect to presigned URL
```

JSON responses include `{cols, rows, types, row_count, size_bytes, _links}`. JSON, CSV, and YAML support `limit`, `offset`, and `columns` on the result fetch. Parquet returns the full file.

The `Is-Stale: true` response header means the result computed successfully but one or more upstream models changed since execution. Re-run if you need fresh data.

### 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`       |

Poll: `GET /api/v1/query/statement/{id}`. Fetch: `GET /api/v1/query/statement/{id}/result`.


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://v2.dataos.info/concepts/foundations/activation/apis/getting-started/querying-data-products/statement-lifecycle.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.