# Query Data 360 Data using Query API Use the Data 360 Query API to execute SQL queries against your Data 360 data using Connect REST endpoints and Apex methods. This API supports Data 360 SQL syntax and is optimized for all Data 360 use cases, from simple data retrieval to complex analytics and integration scenarios. ## Overview The Query API enables you to: - Execute SQL queries against unified data model, data lake, profile, and engagement objects - Process large result sets with built-in pagination - Access data through REST endpoints or Apex methods - Integrate Data 360 data into external applications and workflows ## API Access Methods Choose the method that best fits your integration scenario. ### Connect REST API Use the Connect REST API for most integration scenarios. It provides comprehensive features and integrates seamlessly with Salesforce Platform capabilities. #### Endpoints - [**Submit SQL Query**](https://developer.salesforce.com/docs/data/connectapi/references/spec?meta=createSqlQuery) - **POST** `https://{dne_cdpInstanceUrl}/services/data/v64.0/ssot/query-sql` - Execute SQL queries synchronously and asynchronously - Returns query ID for tracking and result retrieval. You can pass this `queryId` to [`result_scan`](/docs/data/data-cloud-query-guide/references/dc-sql-reference/result-scan.md) to query the cached results in a subsequent SQL statement. - [**Get SQL Query Status**](https://developer.salesforce.com/docs/data/connectapi/references/spec?meta=getSqlQuery) - **GET** `https://{dne_cdpInstanceUrl}/services/data/v64.0/ssot/query-sql/{queryId}` - Check query execution status and metadata - Monitor progress for long-running queries - [**Get SQL Query Rows**](https://developer.salesforce.com/docs/data/connectapi/references/spec?meta=getSqlQueryRows) - **GET** `https://{dne_cdpInstanceUrl}/services/data/v64.0/ssot/query-sql/{queryId}/rows` - Retrieve query results with pagination support - Handle large datasets efficiently - [**Cancel SQL Query**](https://developer.salesforce.com/docs/data/connectapi/references/spec?meta=cancelSqlQuery) - **DELETE** `https://{dne_cdpInstanceUrl}/services/data/v64.0/ssot/query-sql/{queryId}` - Cancel running queries to free up resources - Useful for query timeout management ### Data 360 REST API (Direct API) The Data 360 REST API is an HTTP interface for executing SQL queries directly against your Data 360 data. It includes improved asynchronous execution, richer schema introspection, and consistent error reporting. :::note This API uses the `dne_cdpInstanceUrl`, which is separate from your standard Salesforce org URL. See [Data Cloud API (also known as Direct API)](https://developer.salesforce.com/docs/data/data-cloud-dev/guide/custom-app-dev.md#data-cloud-api-also-known-as-direct-api) for instructions on obtaining the instance URL and access token. ::: #### Endpoints - [**Submit SQL Query**](/docs/data/data-cloud-query-guide/references/data-cloud-query-api-reference/query-api-v3-post.md) - **POST** `/api/v3/query` - Execute queries in ASYNC or ADAPTIVE mode - Returns a `queryId` in the `x-hyperdb-status` response header for polling. - [**Get SQL Query Status**](/docs/data/data-cloud-query-guide/references/data-cloud-query-api-reference/query-api-v3-get-query.md) - **GET** `/api/v3/query/{queryId}` - Poll for query completion status - Returns status, row count, chunk count, and execution statistics. - [**Get SQL Query Rows**](/docs/data/data-cloud-query-guide/references/data-cloud-query-api-reference/query-api-v3-get-rows.md) - **GET** `/api/v3/query/{queryId}/rows` - Retrieve results using offset-based pagination. - [**Get SQL Query Chunks**](/docs/data/data-cloud-query-guide/references/data-cloud-query-api-reference/query-api-v3-get-chunk.md) - **GET** `/api/v3/query/{queryId}/chunks/{chunkId}` - Retrieve results by chunk ID (preferred for large result sets). - [**Get SQL Query Metadata**](/docs/data/data-cloud-query-guide/references/data-cloud-query-api-reference/query-api-v3-get-metadata.md) - **GET** `/api/v3/query/{queryId}/metadata` - Retrieve output schema without fetching data rows. - [**Cancel SQL Query**](/docs/data/data-cloud-query-guide/references/data-cloud-query-api-reference/query-api-v3-delete.md) - **DELETE** `/api/v3/query/{queryId}` - Cancel a running query and free server resources. #### Apache Arrow All Data 360 REST API endpoints return JSON by default. [Apache Arrow IPC streaming format](https://arrow.apache.org/docs/format/IPC.html) is also supported as a columnar binary format that reduces payload size and deserialization overhead, making it the better choice for large result sets. These endpoints support Apache Arrow as an alternative to JSON. - Submit SQL Query - Get SQL Query Rows - Get SQL Query Chunks - Get SQL Query Metadata. To request an Arrow response, set the `Accept` header to `application/vnd.apache.arrow.stream`. The response body is a binary Arrow IPC stream rather than JSON. Use an Arrow-compatible client library (such as [PyArrow](https://arrow.apache.org/docs/python/) or the [Apache Arrow Java library](https://arrow.apache.org/docs/java/)) to read the stream. ### Apex Methods For server-side integration within your Salesforce org, use Apex methods to query Data 360 data. #### sfsqlquery Namespace The [`sfsqlquery` namespace](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_namespace_sfsqlquery.htm) provides object-oriented Apex classes for managing Data 360 SQL query execution with iterators and asynchronous queueables. It includes classes like `SqlStatement`, `SqlRowIterator`, `Row`, `QueryHandle`, and `SqlQueueable` for structured query lifecycle management. This namespace is the recommended approach for querying Data 360 data with Apex. For workflows and usage patterns, see [Query Data 360 Data with Apex](/docs/data/data-cloud-query-guide/guide/dc-apex-query.md). #### ConnectApi.CdpQuery Methods The `ConnectApi.CdpQuery` class provides Apex methods that mirror the Connect REST API endpoints: - [**Submit SQL Query**](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_ConnectAPI_CdpQuery_static_methods.htm#apex_ConnectAPI_CdpQuery_querySql\_1) - Execute SQL queries - [**Get SQL Query Status**](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_ConnectAPI_CdpQuery_static_methods.htm#apex_ConnectAPI_CdpQuery_querySqlStatus\_1) - Check query status - [**Get SQL Query Rows**](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_ConnectAPI_CdpQuery_static_methods.htm#apex_ConnectAPI_CdpQuery_querySqlRows\_1) - Retrieve paginated results - [**Cancel SQL Query**](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_ConnectAPI_CdpQuery_static_methods.htm#apex_ConnectAPI_CdpQuery_cancelQuerySql\_1) - Cancel running queries ## Authentication Authentication requirements vary by access method. ### OAuth 2.0 (REST API) See [OAuth 2.0 Client Credentials Flow for Server-to-Server Integration](https://help.salesforce.com/s/articleView?id=xcloud.remoteaccess_oauth_client_credentials_flow.htm\&type=5) in Salesforce Help. All REST API calls require a valid OAuth 2.0 access token: ```http Authorization: Bearer YOUR_ACCESS_TOKEN Content-Type: application/json ``` ### Session-based (Apex) Apex methods use the current user's session context and permissions automatically. See [Getting Started with Apex](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_intro_get_started.htm) in the Apex Developer Guide. ## Best Practices - **Filter early**: Use WHERE clauses to reduce data scanned - **Select specific columns**: Avoid `SELECT *` statements - **Limit results**: Use `LIMIT` for large datasets - **Optimize joins**: Include key qualifiers and proper indexing - **Consider your data’s indexed field**: Use the DMO’s primary index, or create a [secondary index](https://help.salesforce.com/s/articleView?language=en_US\&id=data.c360\_a_query_secondary_indexes.htm\&type=5) for non-primary fields that you filter or join on frequently. - **Implement asynchronous handling**: Data 360 queries use both asynchronous and synchronous responses to optimize performance. Set up your application to handle both synchronous and asynchronous responses. - **Paginate result sets**: Use the Connect API `getSqlQueryRows` endpoint with `offset` and `rowLimit`. You can query your `createSqlQuery` results for 24 hours without incurring more consumption charges. Because Data 360 stores results, `getSqlQueryRows` returns data faster than calls to `createSqlQuery`. ### Query Optimization ```sql -- ✅ Good: Use WHERE clauses to filter data SELECT ssot__FirstName__c, ssot__LastName__c FROM ssot__Individual__dlm WHERE ssot__CreatedDate__c >= '2024-01-01' AND ssot__IsActive__c = true LIMIT 1000 -- ❌ Avoid: Selecting all data without filters SELECT * FROM ssot__Individual__dlm ``` ### Key Qualifiers in Joins Include key qualifier fields in table joins for optimal performance: ```sql SELECT * FROM ssot__ContactPointEmail__dlm email LEFT JOIN ssot__Individual__dlm individual ON email.ssot__PartyId__c = individual.ssot__Id__c AND email.KQ_PartyId__c IS NOT DISTINCT FROM individual.KQ_Id__c LIMIT 10 ``` When key qualifiers aren't configured on data lake object fields, the value is null. Use `IS NOT DISTINCT FROM` for null-safe joins. ## Related Resources - [Query Services Status Codes](/docs/data/data-cloud-query-guide/references/data-cloud-query-api-reference/c360a-api-queryservices-statuscodes.md) - Error handling reference - [Get Started With Data 360 SQL](/docs/data/data-cloud-query-guide/guide/dc-query-section.md) - SQL tutorial and examples - [Data 360 Metadata API](/docs/data/data-cloud-query-guide/references/data-cloud-query-api-reference/c360a-api-metadata-api.md) - Explore available data objects - [API Limits and Guidelines](https://help.salesforce.com/s/articleView?id=data.c360\_a_limits_and_guidelines.htm\&type=5) - Usage limits and best practices - [*Salesforce Developers Blog:* Boost Data 360 Integrations with the New Query Connect API](https://developer.salesforce.com/blogs/2025/08/boost-data-cloud-integrations-with-the-new-query-connect-api)