Deploy Semarchy xDM in Snowflake

This page guides you through the step-by-step process of accessing, deploying, and using xDM in Snowflake.

Install and setup the Native App

Install the Native App

To install the Semarchy Native App:

Sign in to Snowsight (the Snowflake web interface) with your Snowflake account.
In the navigation menu, go to Data Products Marketplace.
Search for Semarchy xDM and select the Semarchy xDM listing from the search results.
On the listing page, select the Get button to install the app.
Follow the prompts to integrate xDM with your Snowflake environment.

Grant required privileges

To grant the account level privileges to the Semarchy Native App:

In the navigation menu, go to Data Products Apps.
Select the Semarchy xDM app from the Installed App list.
Select the Privileges tab and click the Edit icon on the Account level privileges row.
Ensure CREATE COMPUTE POOL and BIND SERVICE ENDPOINT privileges are granted.
Click Update Privileges.

As mentioned in the prerequisites, non-admin Snowflake users must be granted the application role exposed by the Native App to access xDM. Role creation and assignment are managed entirely within your Snowflake account. For more information, see the official Snowflake documentation.

Configure external network access

To ensure proper operation, you must confirm the external network access configuration. The application requires an access rule to:

Your Snowflake account, which allows the Semarchy Native App to store and access data.
The Semarchy license server, which enables license validation.

Confirm external endpoints

When creating your Native App, a confirmation dialog prompts you to review the required external endpoints:

Verify the allowed endpoints configured for the application.
Expand the Advanced Options section to review the network rule name and location.
Click Connect to confirm.

Extend network access for external services

If your xDM application needs to connect to external services, such as plugins or REST clients like Google Maps or OpenAI, you must extend network access.

Example. Configuring network access for external services

If you want to configure network access for the OpenAI enrichers:

Navigate to Admin Security, select the Network Rules tab, and click Add Network Rule.
Locate the network rule with the location set to <native_app_database> Configuration.
Click the Menu icon and select Edit.
Add an identifier by entering its URL (e.g., api.openai.com) and pressing Enter.
Click Update Network Rule to confirm.

For more details, see the official Snowflake documentation.

Allow access to Snowflake stages for large query results

When executing queries that produce large result sets, Snowflake may temporarily store the data in an internal cloud storage location known as a Snowflake stage. To retrieve this data, the JDBC driver embedded in the Semarchy Native App must be able to access this stage.

Because Snowflake does not automatically grant the Native App access to internal stages, you must manually update the network rule associated with the Native App to authorize outbound connections to the stage location:

Identify your stage endpoint:
1. Run the following query in your Snowflake environment:
  select SYSTEM$ALLOWLIST();
2. In the results, look for entries containing STAGE. These identify the internal stage hostnames that must be allowed in the network rule.
Add the stage location to the network rule:
1. Navigate to Admin Security, and select the Network Rules tab.
2. Locate the network rule associated with the Semarchy Native App (typically under <native_app_database> Configuration).
3. Edit the rule and add the stage host or full identifier (e.g., *.<cloud-storage-domain>, or the exact stage endpoint returned by Snowflake, such as <stage-identifier>.<storage-service>.<region>.<cloud-domain>).
4. Save the network rule.

This configuration allows the Native App’s JDBC driver to access temporary result data stored by Snowflake, and ensures correct processing of large query results.

Prepare the setup token

Before starting the Native App, you need to create a setup token. This token authenticates you during the initial configuration of the administrator login and password, and must be provided as a parameter in the start_app procedure in the next step.

After completing the initial setup, the token is no longer required and can be discarded for security purposes.

Start the Semarchy Native App

To start the Semarchy Native App and create the necessary containers, execute the following stored procedure:

CALL <native_app_name>.xdm_public.start_app(
    <setup_token>,
    [<instance_family>],
    [<volume_size>],
    [<volume_iops>],
    [<volume_throughput>],
    [<workitemsexec_interval>]
);

Below is a detailed description of each parameter:

Parameter

Required

Description

<setup_token>

Yes

The xDM setup token, required during the first connection to seed the repository.

<instance_family>

The type of compute instance provisioned for xDM application and repository containers (default: CPU_X64_S). For the list of allowed values, see the official Snowflake documentation.

<volume_size>

The storage volume size (in GB) used by the repository container (default: 5). For more information, see the official Snowflake documentation.

<volume_iops>

The maximum input/output operations per second (IOPS) supported for the repository storage (default: 3000). For more information, see the official Snowflake documentation.

<volume_throughput>

The peak throughput (in MiB/s) supported for the repository storage (default: 125). For more information, see the official Snowflake documentation.

<workitemsexec_interval>

The interval (in seconds) between each check for workflow items to process (default: 10).

Once executed, this procedure provisions and starts the xDM application within your Snowflake environment.

Retrieve the xDM server URL

To obtain the URL of the xDM server, execute the following stored procedure:

CALL <native_app_name>.xdm_public.xdm_server_url();

Once retrieved, you can access xDM at https://<xdm_server_url>/semarchy.

Logging into xDM requires two-factor authentication, as mandated by Snowflake. This includes both Snowflake authentication and xDM authentication.

To enable single sign-on (SSO), configure OKTA for both Snowflake and xDM.

Access the REST API with programmatic access tokens

You can call the xDM REST API exposed by the Native App using Snowflake programmatic access tokens (PATs). PATs provide a secure, Snowflake-managed mechanism to authenticate external tools such as Postman, scripts, and automation workflows.

PATs are required when calling the xDM REST endpoints because the Native App enforces Snowflake authentication as part of its security model.

Prerequisites

Before calling the xDM REST API:

Ensure the Semarchy Native App is deployed and running.

Retrieve the xDM server URL using:

CALL <native_app_name>.xdm_public.xdm_server_url();

Generate a PAT in Snowflake

PATs are created and managed entirely in Snowflake. For instructions on generating a PAT, see the official Snowflake documentation.

PAT issuance, renewal, and revocation are controlled by your Snowflake account configuration.

Authenticate REST API calls with a PAT

To call xDM endpoints using a PAT:

Open your preferred API tool or HTTP client.
Create a new HTTP request.
Select the appropriate HTTP method (e.g., GET, POST) for the xDM REST endpoint you want to call.

Set the request URL to:

https://<xdm_server_url>/semarchy/api/<endpoint>

Add the Authorization header using the custom Snowflake token format required for PAT authentication:
```
Authorization: Snowflake Token="<your_pat_token>"
```
Endpoints exposed through Snowflake Container Services do not accept the standard Bearer authentication scheme.
Send the request.

Configure datasources

After installing and accessing xDM for the first time, you need to declare the Snowflake datasource. This datasource must reference the database schema you created for storing your master data, as mentioned in the prerequisites.

For more information, see Configure datasources.