Getting real value from your data often means sifting through massive datasets, which can be a slow and challenging task. To make data access faster and more efficient, Salesforce has released the new Data Cloud Query Connect API, which supersedes the V1 & V2 Query API. 

The Data Cloud Connect API is the programmatic interface for interacting with your unified customer data. “Connect” signifies its ability to manage and activate core Data Cloud assets, such as segments and calculated insights. Its comprehensive capabilities go beyond simple data retrieval: users can execute SQL queries for advanced analytics, reporting, and external application integration, making the “Query” aspect central to its powerful data access.

In this post, we’ll give you a brief overview of the new Query Connect API and share an example scenario that shows it in action.

About the new Query Connect API

The new Query Connect API is designed to make your data queries more performant and scalable. Now there’s no limit on the number of rows that can be retrieved and query results are available for up to 24 hours. Parameterized queries and row-based pagination are fully supported, ensuring flexibility and efficiency in your data handling. In addition, the API returns more helpful error messages, making it easy to use and debug.

The API is powered by the Hyper SQL engine, which is built for speed. It allows you to handle complex queries on large datasets and retrieve gigabyte-scale results quickly, outperforming systems like Trino, Snowflake, and Redshift.

Here are the new Data Cloud Query Connect API endpoints:

  • POST /ssot/query-sql: Submit a query request for execution and receive the first batch of rows
  • GET /ssot/query-sql/{queryId}: Check the status of a query request
  • GET /ssot/query-sql/{queryId}/rows: Get additional data that wasn’t returned in the initial query request
  • DELETE /ssot/query-sql/{queryId}: Cancel a long running query request if needed

Example scenario: Retrieving campaign engagement records

Imagine that Sarah, a data specialist at “Growth Insights Inc.,” needs to retrieve all campaign engagement records from the
CampaignEngagement__dll data lake object (DLO) since January 1, 2025. Her goal is to perform a comprehensive audit of data ingestion, verify data integrity, and analyze user activity related to customer interactions. Sarah knows that the total number of records is expected to be very large — perhaps 100,000 records.

The new Query Connect API is designed to make this kind of massive data retrieval manageable and efficient. Let’s walk through how Sarah would first submit her query, then check its status as it processes, and finally, retrieve the full results using pagination.

Sequence diagram showing the requests for querying data with the Query Connect API

Step 1: Submit the query request

Sarah uses POST /ssot/query-sql (see docs) to initiate the query execution in Data Cloud.

Query parameters:

  • dataspace=default: The data space where the query should be executed.
  • workloadName=connect-engagement-records: Description of the scenario, task, or application name that Sarah’s query handles. She sets this value to help Salesforce Customer Support assist her with debugging issues.

Request: The sqlParameters array is used for parameterized queries. Here, :startDate is a placeholder for the actual date value. See the Data Cloud SQL Syntax for more information on SQL statements.

Response: The API immediately returns a queryId to track the query’s progress, metadata about the result columns, and the first chunk of data (e.g., 2000 rows). The completionStatus is ResultsProduced because the first chunk is ready, but rowCount indicates that more data is available. Query results are also subject to result caching, meaning identical queries submitted within a specific timeframe can be served much faster. These cached results have a 24-hour expiration time, ensuring that they remain available for repeated access and optimizing performance for frequently run queries.

Step 2: Check the query status

Since the initial response indicated rowCount is 100,000, but only 2,000 rows were returned, Sarah’s query is still processing in the background. The client needs to periodically check its status using GET /ssot/query-sql/{queryId} (see docs).
Query parameters:

  • dataspace=default: The data space where the query should be executed.
  • workloadName=connect-engagement-records: Description of the scenario, task, or application name that Sarah’s query handles. She sets this value to help Salesforce Customer Support assist her with debugging issues.
  • waitTimeMs: This parameter allows the client to perform long polling. The API will block for up to waitTimeMs (e.g., 10,000ms = 10 seconds) if the status hasn’t changed, or return immediately if it has. Sarah can adjust this number as needed in case she encounters any Apex resource limit issues.

Request: The client might poll every five seconds until the query completionStatus is FINISHED. Notice that the queryId obtained in the previous response is used as part of the URL for this status check.

Response 1: The progress field indicates how much of the query has been processed.

Response 2: Once completionStatus is FINISHED (or ResultsProduced and progress is 1.0), all data is ready for retrieval.

Step 3: Get additional rows (row-based pagination)

After confirming that Sarah’s query is complete, the client fetches the remaining 98,000 rows using GET /ssot/query-sql/{queryId}/rows (see docs).
Query parameters:

  • rowLimit: The maximum number of rows to return in this chunk (e.g., 2000).
  • offset: The row number to start with when retrieving the next chunk of query results.
  • omitSchema=true: This parameter, when set to true, tells the API not to return the metadata (metadata array) with each subsequent chunk. This is useful for reducing the amount of data returned to have a faster performance.

Request: Get the next 2000 rows, starting from row 2000 (since the first 2000 were already received).

Response: The response contains the next chunk of data.

Step 4: Delete a long-running query (optional)

For queries that are no longer needed due to user cancellation or long-running queries, Sarah simply uses the DELETE /ssot/query-sql/{queryId} (see docs) endpoint.

Integrated tools

Beyond just speed, the new API offers features designed to make your development process smoother. Take advantage of out-of-the-box UI tools like the Postman collection, the Data Cloud Query Editor, DBeaver, Tableau Cloud, and Tableau Desktop. These tools make it simple to work with the API without the need for coding.

The Data Cloud Connect API Postman collection in the Salesforce Developers workspace

Conclusion

In this post, we explored the new Data Cloud Query Connect API, discussed their key features, and walked though a practical example of how to use them for data retrieval and status monitoring. The new Query Connect API is ready to use in the Salesforce Developers Postman workspace. Check out this quick start video to familiarize yourself with the Connect APIs (Note: the new Query API is not included). And, see the Data Cloud Query Guide to help you with your querying. 

Resources

About the author

Nicole Arcolino is a Technical Writing Analyst at Salesforce, specializing in Data Cloud API and data modeling documentation. Follow her on LinkedIn.