Query Data using Query API

The Data Cloud Query API provides a powerful way to execute SQL queries against your Data Cloud data using Connect REST endpoints and Apex methods. This API supports Data Cloud SQL syntax and is optimized for all Data Cloud use cases, from simple data retrieval to complex analytics and integration scenarios.

The Query API enables you to:

  • Execute SQL queries against data streams, profile, engagement, and unified data model objects
  • Handle both synchronous and asynchronous query execution
  • Process large result sets with built-in pagination
  • Access data through REST endpoints or Apex methods
  • Integrate Data Cloud data into external applications and workflows

Use the Connect REST API for most integration scenarios. It provides comprehensive features and integrates seamlessly with Salesforce Platform capabilities.

Base URL: https://{dne_cdpInstanceUrl}/services/data/v64.0/ssot/query-sql

  • Create SQL Query

    • POST https://{dne_cdpInstanceUrl}/services/data/v64.0/ssot/query-sql
    • Execute SQL queries asynchronously
    • Returns query ID for tracking and result retrieval

  • Get SQL Query Status

    • 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 Results

    • 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

    • DELETE https://{dne_cdpInstanceUrl}/services/data/v64.0/ssot/query-sql/{queryId}
    • Cancel running queries to free up resources
    • Useful for query timeout management

For server-side integration within your Salesforce org, use the Apex ConnectAPI methods:

See Configure a Connected App for the OAuth 2.0 Client Credentials Flow in the Salesforce Help Guide. All REST API calls require a valid OAuth 2.0 access token:

Apex methods use the current user's session context and permissions automatically. See Getting Started with Apex in the Apex Developer Guide.

  • 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 DMOs primary index or consider using a secondary index

Include key qualifier fields in table joins for optimal performance:

When key qualifiers aren't configured on data lake object fields, the value is null. Use IS NOT DISTINCT FROM for null-safe joins.

  • Monitor your API usage limits
  • Implement exponential backoff for 429 responses
  • Use asynchronous queries for long-running operations
  • Cache frequently accessed data when possible
  • Use async queries for operations taking longer than 30 seconds
  • Implement pagination for result sets larger than 1000 rows
  • Cancel long-running queries that are no longer needed
  • Monitor query performance and adjust as needed