Setting Up the B2C Commerce Intelligence JDBC Driver

This section describes how to configure your JDBC driver and connect it to the B2C Commerce Data Lakehouse. The B2C Commerce Data Lakehouse is a centralized data repository that stores and organizes B2C Commerce Cloud transactional data, customer interactions, and business metrics in a structured format optimized for analytics and reporting. It serves as the foundation for the Commerce Intelligence JDBC Driver, providing access to pre-aggregated business data through standardized SQL queries.

The data lakehouse contains:

  • Fact tables (for example, line items, orders, payments, inventory snapshots)
  • Dimension tables (for example, products, customers, sites, dates, geographies)
  • Aggregate tables (for example, daily sales summaries, search analytics, promotion performance)

This architecture enables business users to perform complex analytics on e-commerce data, supporting use cases like sales analytics, customer behavior analysis, inventory optimization, and marketing campaign effectiveness measurement.

  1. Account Setup: Your current account typically has the necessary permissions to access data using the JDBC driver. No additional roles are required.
  2. Role: Salesforce Commerce API
  3. Tenant Filter: To authenticate successfully, you must add the appropriate tenant filter. You can specify multiple tenant IDs as needed.

The Commerce Intelligence JDBC Driver enables seamless connectivity to your B2C Commerce data lakehouse through a JDBC interface, ensuring compatibility with various SQL editors and data visualization tools.

There are two ways to download the Commerce Intelligence JDBC Driver:

Download the latest version directly from the Salesforce Commerce Cloud GitHub Repository. For detailed installation steps, refer to the README file in the repository.

Authentication steps may be required to access the repository. This documentation will be updated with detailed instructions on how to authenticate and download the driver.

Include the driver as a Maven dependency in your Java project. This is helpful if you're building a custom application and want to manage dependencies via Maven.

Add the following to your pom.xml:

Find the latest version on Maven Repository.

For demonstration purposes, this document uses DBeaver as an example SQL editor. However, the Commerce Intelligence JDBC Driver is compatible with any JDBC-compliant tool, such as SQL Workbench, DataGrip, or custom Java applications.

To use the driver in DBeaver:

  1. Open DBeaver.
  2. Go to Database → Driver Manager.
  3. Click New.
  4. Enter the Driver Name (for example, "CommerceIntelligenceDriver").
  5. Specify the Driver Class: com.salesforce.commerce.intelligence.jdbc.client.CIPDriver.
  6. Add the Driver JAR:
    1. Click the Libraries tab.
    2. Click Add File, and select the driver JAR file you downloaded.
    3. Click Find Driver.
  7. Click OK.
  8. Create a database connection:
    1. Navigate to Database → New Database Connection.
    2. Select the driver you registered and click Next.

A JDBC Driver connection enables you to access analytics data used for Reports and Dashboards. It doesn't establish a connection to your B2C commerce instance or to Business Manager, and it can't be used to modify your live site.

The following properties must be configured to connect to your B2C Commerce data lakehouse:

PropertyDescriptionTypeRequiredExample
JDBC URLSpecifies the B2C Commerce database connection string, including the target instance. Replace the {your_instance_id} placeholder with your actual TenantId, which uniquely identifies your tenant's data environment.StringYesjdbc:salesforcecc://jdbc.analytics.commercecloud.salesforce.com:443/{your_instance_id}
UsernameThe Client ID provided by your Account Manager.StringYesyour-client-id
PasswordThe Client Secret provided by your Account Manager.StringYesyour-client-secret

You can also use the Commerce Intelligence JDBC Driver directly in your Java applications. The following sample code demonstrates how to connect and query your B2C Commerce data:

Keep the following best practices in mind when issuing queries to Commerce Cloud:

  1. Always ensure your queries use an index column to ensure optimal query performance
  2. Rewrite your query against an aggregate table whenever possible, as queries over aggregate tables are significantly faster
  3. Never run queries like SELECT * FROM <TABLE> against tables with thousands of rows
  4. Design data extraction for large datasets to retrieve data across multiple batches using incremental processing techniques. Primary keys generated with sequence numbers allow for incremental extraction of data

The following non-functional limits and behaviors apply when using the B2C Commerce Intelligence connector. Please review these carefully to avoid unexpected errors or interruptions:

  • Queries have a maximum execution time of 30 minutes.
  • Any query exceeding this limit will be automatically terminated.
  • To avoid timeouts, optimize your queries using indexing, aggregations, and batching techniques.
  • SQL queries are case-sensitive.
  • Make sure all table and column names match the exact casing used in the schema documentation.
  • You can download up to 25 GB of data per day through the JDBC driver.
  • The quota resets daily at 12:00 AM UTC.
  • Once the limit is reached, further queries will be blocked until the quota resets.
  • You can execute up to 10 queries per minute.
  • Each query that returns more than 450,000 rows will count as multiple queries toward this limit.
  • For example, a query that returns 900,000 rows will count as 2 queries.
  • If you exceed the rate limit, additional queries will be temporarily throttled.

Here are some sample queries:

Is there any difference in data availability (time) in Reports and Dashboards vs via JDBC driver?

No. Data will be available at the same time in Reports and Dashboards as well as JDBC driver.

Do you plan to make more data available for access through JDBC driver?

Yes, more information will be shared closer to release time.