--- cuppy_hub: salesforce cuppy_path: reference/official/data360/data-cloud-query-guide/references/data-cloud-query-api-reference/query-api-migration.md cuppy_section: docs cuppy_doc: QD01-Z7GP cuppy_doc_uuid: 9f23f51a-7e3a-4eb8-8351-f459e9b56f7f cuppy_permalink: https://cuppy.io/salesforce/d/QD01-Z7GP cuppy_version: 1 cuppy_updated: 2026-10-23T16:16:52.575Z cuppy_canonical: https://cuppy.io/salesforce/docs/reference/official/data360/data-cloud-query-guide/references/data-cloud-query-api-reference/query-api-migration cuppy_mcp: https://cuppy.io/mcp cuppy_body_sha256: a1d629bdf8349893cc35fcfe6cd4f91ac25e76d212906f68a2fd26f227d23dc9 # cuppy_body_sha256 is over the document body ALONE, excluding both generated blocks. --- > Mirror of (Salesforce, Data 360 Query Guide), read 2026-10-23. Salesforce's own page is the authority; this copy exists because that site refuses non-browser readers. ## Migrate to Query API V3 Use this guide to update integrations built on Query API V1 or V2 to the Data 360 Query API V3. Query API V3 introduces asynchronous and adaptive execution modes and standardizes error reporting. Review the considerations and SQL function mapping tables before migrating. | V1 / V2 Endpoint | V3 Endpoint | Notes | | --- | --- | --- | | `POST /api/v1/query` | `POST /api/v3/query` | V1 was synchronous only; V3 supports ASYNC and ADAPTIVE modes. | | `POST /api/v2/query` | `POST /api/v3/query` | Request body field name is `sql` in both versions. | | `GET /api/v2/query/{nextBatchId}` | `GET /api/v3/query/{queryId}/chunks/{chunkId}` (preferred) or `GET /api/v3/query/{queryId}/rows` | Replace `nextBatchId` with `queryId`. For chunks, use `chunkId` from `chunkCount`. For rows, add `?offset=0`. | | — | `GET /api/v3/query/{queryId}` | New in V3: poll for query completion status. | | — | `GET /api/v3/query/{queryId}/metadata` | New in V3: retrieve output schema without fetching data rows. | | — | `DELETE /api/v3/query/{queryId}` | New in V3: cancel a running query and free resources. | | - | `GET /api/v3/query/{queryId}/chunks/{chunkId}` | New in V3: retrieve a chunk of query data. | Review the following behavioral changes before migrating. Query API V1 returned results inline in the POST response. Query API V3 doesn’t support synchronous execution. Use ADAPTIVE mode to receive results immediately for fast queries, or ASYNC mode for long-running queries. In both modes, retrieve the `queryId` from the `x-hyperdb-status` response header to poll for status or fetch results. Query API V3 standardizes error responses using SQLSTATE codes and a rich error model. Update any code that parsed error strings. See [Query API V3 Error Handling](https://developer.salesforce.com/docs/data/data-cloud-query-guide/references/data-cloud-query-api-reference/query-api-v3-post.html#error-handling) for the error format. The Query API V3 HTTP endpoint uses `sql` for the query field. Confirm whether any Query API V1 integrations used a different field name. Query API V3 changes how output column names are cased. * **Query API V1 and V2:** Output column name casing matches exactly what was written in the `SELECT` clause. * **V3 with alias:** Output column name uses the exact casing of the alias. Use quoted aliases to guarantee specific casing. * **V3 without alias:** Output column name reverts to the casing defined in the underlying table schema, regardless of how the column was written in the `SELECT` clause. This is a breaking change for downstream code that relies on exact column name matching for non-aliased columns. To guarantee output casing, use explicit quoted aliases. In Query API V1 and V2, expressions without aliases (for example, `SELECT count(*), sum(x) FROM ...`) produced output column names `_col0`, `_col1`. In Query API V3, the same expressions produce `1`, `2`. The following functions are renamed, replaced, or removed. | V1/V2 | V3 | Notes | | --- | --- | --- | | `DATE_FORMAT(date, format)` | [`TO_CHAR(date, format)`](https://developer.salesforce.com/docs/data/data-cloud-query-guide/references/dc-sql-reference/to-char.html) | Format patterns differ: V1/V2 uses `'yyyy'`; V3 uses `'YYYY'`. | | `DATE_PARSE(string, format)` | [`TO_TIMESTAMP(text, text)`](https://developer.salesforce.com/docs/data/data-cloud-query-guide/references/dc-sql-reference/to-timestamp-string.html) | Parses formatted text into a timestamp. | | `DATE_ADD(unit, value, date)` | [`DATE_ADD(unit, value, date)`](https://developer.salesforce.com/docs/data/data-cloud-query-guide/references/dc-sql-reference/date-add.html) or `date + INTERVAL 'value' unit` | V3 example: `DATE_ADD('day', 3, TIMESTAMP '2025-01-01 00:00:00')`. See the linked `DATE_ADD` reference for supported units; HyperSQL compatibility depends on target product. | | `DATE_SUB(unit, value, date)` | `DATE_ADD(unit, value, date)` or `date - INTERVAL 'value' unit` | `DATE_SUB` is not supported. Use a negative value with `DATE_ADD` or interval subtraction. | | `DATE_DIFF(unit, date1, date2)` | [`DATEDIFF(unit, date1, date2)`](https://developer.salesforce.com/docs/data/data-cloud-query-guide/references/dc-sql-reference/datediff.html) | Minor discrepancies are possible for day/month/year boundaries. | | `TODAY()` | [`CURRENT_DATE`](https://developer.salesforce.com/docs/data/data-cloud-query-guide/references/dc-sql-reference/current-date.html) | Function name change. | | `FROM_UNIXTIME(epoch)` | [`TO_TIMESTAMP(double precision)`](https://developer.salesforce.com/docs/data/data-cloud-query-guide/references/dc-sql-reference/to-timestamp.html) | Converts Unix epoch seconds to a timestamp. `FROM_UNIXTIME` isn’t supported. | | `TO_UNIXTIME(timestamp)` | [`EXTRACT(EPOCH FROM timestamp)`](https://developer.salesforce.com/docs/data/data-cloud-query-guide/references/dc-sql-reference/extract.html) | | | V1/V2 | V3 | Notes | | --- | --- | --- | | `FROM_ISO8601_TIMESTAMP(string)` | [`CAST(string AS timestamptz)`](https://developer.salesforce.com/docs/data/data-cloud-query-guide/references/dc-sql-reference/type-conversion.html) | | | `TO_ISO8601(timestamp)` | [`TO_CHAR(timestamp, format)`](https://developer.salesforce.com/docs/data/data-cloud-query-guide/references/dc-sql-reference/to-char.html) | See [`TO_CHAR`](https://developer.salesforce.com/docs/data/data-cloud-query-guide/references/dc-sql-reference/to-char.html) for DATE, TIMESTAMP, and TIMESTAMP WITH TIME ZONE format patterns. | | `FORMAT_DATETIME(timestamp, format)` | [`TO_CHAR(timestamp, format)`](https://developer.salesforce.com/docs/data/data-cloud-query-guide/references/dc-sql-reference/to-char.html) | `FORMAT_DATETIME` is not supported. Use `TO_CHAR` with an equivalent format pattern. | | V1/V2 | V3 | Notes | | --- | --- | --- | | `ARRAY_JOIN(array, delimiter)` | [`ARRAY_TO_STRING(array, delimiter)`](https://developer.salesforce.com/docs/data/data-cloud-query-guide/references/dc-sql-reference/array-to-string.html) | Function name change. | | V1/V2 | V3 | Notes | | --- | --- | --- | | `APPROX_DISTINCT(column)` | [`APPROX_COUNT_DISTINCT(column)`](https://developer.salesforce.com/docs/data/data-cloud-query-guide/references/dc-sql-reference/approx-count-distinct.html) | Function name change. | | `APPROX_PERCENTILE(column, p)` | [`PERCENTILE_CONT`](https://developer.salesforce.com/docs/data/data-cloud-query-guide/references/dc-sql-reference/percentile-cont.html) or [`PERCENTILE_DISC`](https://developer.salesforce.com/docs/data/data-cloud-query-guide/references/dc-sql-reference/percentile-disc.html) | Syntax change; uses `WITHIN GROUP (ORDER BY ...)`. | | `STDDEV(column)` | [`STDDEV` / `STDDEV_SAMP(column)`](https://developer.salesforce.com/docs/data/data-cloud-query-guide/references/dc-sql-reference/stddev.html) or [`STDDEV_POP(column)`](https://developer.salesforce.com/docs/data/data-cloud-query-guide/references/dc-sql-reference/stddev-pop.html) | `STDDEV` and `STDDEV_SAMP` are aliases (sample standard deviation). Use `STDDEV_POP` for population standard deviation. | | `COUNT_IF(condition)` | [`COUNT(*) FILTER (WHERE condition)`](https://developer.salesforce.com/docs/data/data-cloud-query-guide/references/dc-sql-reference/filter-clause.html) | Syntax change. | | V1/V2 | V3 | | --- | --- | | `IF(condition, true_result, false_result)` | [`CASE WHEN condition THEN true_result ELSE false_result END`](https://developer.salesforce.com/docs/data/data-cloud-query-guide/references/dc-sql-reference/case.html) | | V1/V2 | V3 | | --- | --- | | `TRY(CAST(expression AS type))` | [`TRY_CAST(expression AS type)`](https://developer.salesforce.com/docs/data/data-cloud-query-guide/references/dc-sql-reference/type-conversion.html) | | `CARDINALITY(array)` | [`ARRAY_LENGTH(array)`](https://developer.salesforce.com/docs/data/data-cloud-query-guide/references/dc-sql-reference/array-length.html) | | Function | Notes | | --- | --- | | `ROW()` | Not supported. | | `COUNT(DISTINCT a, b)` | Multi-column `COUNT(DISTINCT ...)` is not supported. | | `UUID()` | Not supported. | | `RAND()` | Not supported. Use [`RANDOM()`](https://developer.salesforce.com/docs/data/data-cloud-query-guide/references/dc-sql-reference/random.html) instead. | | `XXHASH64()` | Not supported. | | `TRY()` | Not supported. Use [`TRY_CAST`](https://developer.salesforce.com/docs/data/data-cloud-query-guide/references/dc-sql-reference/type-conversion.html) for safe type conversion. | **Before (V2):** **After (V3):** * [Submit SQL Query](https://developer.salesforce.com/docs/data/data-cloud-query-guide/references/data-cloud-query-api-reference/query-api-v3-post.html) * [Get SQL Query Status](https://developer.salesforce.com/docs/data/data-cloud-query-guide/references/data-cloud-query-api-reference/query-api-v3-get-query.html) * [Get SQL Query Rows](https://developer.salesforce.com/docs/data/data-cloud-query-guide/references/data-cloud-query-api-reference/query-api-v3-get-rows.html) * [Query Services Status Codes](https://developer.salesforce.com/docs/data/data-cloud-query-guide/references/data-cloud-query-api-reference/c360a-api-queryservices-statuscodes.html) --- You are reading one file. The same content is free over MCP at https://cuppy.io/mcp with no signup: ranked search across all 376 documents in this hub, the merged view when you work in a layer, known workarounds matched to the error you hit, and depth control so you spend tokens on what you need. Start with the `_hello` tool. How to connect: https://cuppy.io/salesforce/ Something wrong in this document? Report it with the `session feedback` tool on the same endpoint.