Manage the Semarchy Native App

This page provides SQL commands for monitoring, operating, and maintaining the Semarchy Native App on Snowflake.

The Native App supports two repository modes:

Embedded repository (PostgreSQL container managed within Snowflake)
External repository (existing PostgreSQL database)

Repository-related commands on this page, such as the repository log, backup, and restore procedures, apply only to the embedded repository mode. All other commands, including the procedure that drops obsolete data location tables, apply to both repository modes.

For more information on repository modes, see Install:snowflake/deploy-in-snowflake.adoc#_select_the_repository_mode.

The README file available in the Native App settings provides usage examples for each procedure.

Initial setup and verification

Install the Native App

To install the Native App from the Snowflake Marketplace, run:

CREATE APPLICATION <native_app_name> FROM APPLICATION PACKAGE <app_package_name>;

Verify installation status

To verify that the Native App services are running, run:

CALL <native_app_name>.xdm_public.service_status();

In embedded repository mode, both the xDM application container and the repository container should report a READY status.

Configure parameters

To update Native App configuration parameters, run:

CALL <native_app_name>.xdm_public.reload_app(<params>);

The reload_app procedure restarts the xDM service, which causes a short service interruption.

The <params> argument is a JSON object (VARIANT) containing configuration keys used to update the Native App configuration. These keys are grouped into two categories:

Application configuration parameters, which control how the Native App runs.
Repository connection parameters, which define how the Native App connects to the repository in external repository mode.

Parameter behavior

For each key in <params>:

If the key is not provided, the previously saved value is retained.
If the key is provided with a value, the value is updated and saved.
If the key is provided with null, the value is cleared and reset to its default or inactive state.
When constructing the JSON object, OBJECT_CONSTRUCT_KEEP_NULL ensures that keys set to null are preserved and their corresponding values are cleared.

Application configuration parameters

Key

Description

catalina_opts

Additional JVM options for the Semarchy application container. For more information, see Configure JVM options.

cors_allow_origin

The allowed origins for the UI endpoint. Required to enable CORS.

cors_allow_methods

The allowed HTTP methods for CORS.

cors_allow_headers

The allowed request headers for CORS.

cors_expose_headers

The response headers exposed to the browser.

platform_metrics

A a Boolean flag indicating whether Snowflake platform metrics collection is enabled for the running xDM service (default: false).

vol_size^*

The size (in GB) of the block storage volume for the repository container (default: 5).

vol_iops^*

The maximum input/output operations per second (IOPS) supported for the repository storage (default: 3000).

vol_throu^*

The peak throughput (in MiB/s) supported for the repository storage (default: 125).

^* Storage-related parameters apply only to the embedded repository mode and are ignored when using an external repository.

Configure JVM options

Use the catalina_opts parameter to pass JVM options to the Semarchy application container.

To update the JVM options for the Native App, run:

CALL <native_app_name>.xdm_public.reload_app(
    OBJECT_CONSTRUCT(
        'catalina_opts',
        '-D<property_name>=<value>'
    )
);

Changes to catalina_opts take effect after the Native App reloads.

To configure multiple JVM options, provide them as a single string, separated by spaces:

CALL <native_app_name>.xdm_public.reload_app(
    OBJECT_CONSTRUCT(
        'catalina_opts',
        '-D<property_name_1>=<value_1> -D<property_name_2>=<value_2>'
    )
);

To reset the JVM options to their default state, run:

CALL <native_app_name>.xdm_public.reload_app(
    OBJECT_CONSTRUCT_KEEP_NULL(
        'catalina_opts',
        null
    )
);

For details on how null values are handled, see Parameter behavior.

Configure CORS parameters

Use the cors_allow_origin, cors_allow_methods, cors_allow_headers, and cors_expose_headers parameters to control cross-origin resource sharing (CORS) for the Native App user interface endpoint.

To enable CORS and configure the allowed origins, methods, and headers, run:

CALL <native_app_name>.xdm_public.reload_app(
    {
    'cors_allow_origin': ['<allowed_origin_url_1>', '<allowed_origin_url_2>'],
    'cors_allow_methods': ['<http_method_1>', '<http_method_2>'],
    'cors_allow_headers': ['<request_header_1>', '<request_header_2>'],
    'cors_expose_headers': ['<response_header_1>', '<response_header_2>']
    }::VARIANT
);

Changes to CORS parameters take effect after the Native App reloads.

To disable CORS, clear all CORS parameters by passing null for each key:

CALL <native_app_name>.xdm_public.reload_app(
    OBJECT_CONSTRUCT_KEEP_NULL(
        'cors_allow_origin', null,
        'cors_allow_methods', null,
        'cors_allow_headers', null,
        'cors_expose_headers', null
    )
);

Repository connection parameters

Key

Description

repository_url

The JDBC URL of the external repository. If null is provided, the previously saved value is retained. Cannot be cleared once set.

repository_username

The PostgreSQL user for the repository. Stored as a Snowflake Secret. If not provided, the previously saved value is retained. Can be cleared by passing null.

repository_password

The password for the repository user. Stored as a Snowflake Secret. If not provided, the previously saved value is retained. Can be cleared by passing null.

repository_ro_username

The PostgreSQL read-only user. Stored as a Snowflake Secret. If not provided, the previously saved value is retained. Can be cleared by passing null.

repository_ro_password

The password for the read-only user. Stored as a Snowflake Secret. If not provided, the previously saved value is retained. Can be cleared by passing null.

Monitor the Native App

Check service status

To check the status of the Native App services, run:

CALL <native_app_name>.xdm_public.service_status();

For users who only need to check service status and view logs, granting the DM_MONITOR application role avoids giving them administration privileges. For more information, see Grant monitoring access.

View application logs

To display logs from the xDM application container:

CALL <native_app_name>.xdm_public.xdm_server_logs([<number_of_lines>]);

View repository logs

To display logs from the repository container (embedded repository mode only):

CALL <native_app_name>.xdm_public.xdm_repo_logs([<number_of_lines>]);

In external repository mode, repository logs are not available through Native App procedures. Logs must be accessed through the database platform hosting the external repository.

Collect platform metrics

The Native App can publish container-level metrics for the xDM service to the event table of the Snowflake account. Metric collection is disabled by default.

When metric collection is enabled, Snowflake records the following metric groups:

system: CPU and memory usage
system_limits: CPU and memory limits and requests
status: container state and restarts
network: egress bytes and packets, including packets denied by network rules, and ingress connections
storage: block storage volume capacity, usage, IOPS, and throughput

Metrics remain in the event table of your own Snowflake account. The Native App does not expose any procedure to read them. To read them, use the Snowflake SPCS_GET_METRICS function or query the event table, as described in Query platform metrics.

Container logs are not exported to the event table. To view logs, use the log procedures described in [_monitor_the_native_app].

Metrics cover the running xDM service only.

Enable platform metrics collection

To enable platform metrics collection:

Ensure that an event table is set as the active event table for your Snowflake account. For more information, see the official Snowflake documentation.
Run the following procedure to reload the Native App with the platform_metrics parameter set to TRUE:
```
CALL <native_app_name>.xdm_public.reload_app(OBJECT_CONSTRUCT('platform_metrics', TRUE));
```
The reload_app procedure restarts the xDM service, which causes a short service interruption.

The platform_metrics value is saved with the other configuration parameters. It is preserved across reloads, version upgrades, and repository mode switches.

Setting platform_metrics to true in the <params> argument of the startup procedure enables metric collection from the first startup, without a later reload. For more information, see Install:snowflake/deploy-in-snowflake.adoc#start-native-app.

Disable platform metrics collection

To stop collecting platform metrics, run the following procedure to reload the Native App with the platform_metrics parameter set to FALSE:

CALL <native_app_name>.xdm_public.reload_app(OBJECT_CONSTRUCT('platform_metrics', FALSE));

The reload_app procedure restarts the xDM service, which causes a short service interruption.

Metric collection stops when the reload completes.

Grant monitoring access

The Native App exposes a read-only DM_MONITOR application role that lets users monitor the xDM service without administration privileges.

To grant monitoring access, run:

GRANT APPLICATION ROLE <native_app_name>.DM_MONITOR TO ROLE <account_role_name>;

The DM_MONITOR application role grants:

Access to service metrics through SPCS_GET_METRICS, without any privilege on the event table itself.
Access to the service_status, xdm_server_logs, and xdm_repo_logs procedures.

It does not grant access to administration procedures (such as start_app, reload_app, stop_app, and backup and restore procedures), to repository credentials, to the xDM user interface, or to master data.

Query platform metrics

To query the platform metrics of the xDM service:

Run the following query:

SELECT * FROM TABLE(<native_app_name>.XDM_APP_SCHEMA.xdm!SPCS_GET_METRICS());

The SPCS_GET_METRICS function is called on the xdm service, which is in the XDM_APP_SCHEMA schema. The XDM_PUBLIC schema only contains the Native App procedures.

For information about the available query options and the returned metrics, see the official Snowflake documentation.

Example

To return the metrics recorded over the last three days, run:

SELECT *
FROM TABLE(<native_app_name>.XDM_APP_SCHEMA.xdm!SPCS_GET_METRICS(
    start_time => DATEADD('day', -3, CURRENT_TIMESTAMP())
));

Platform metrics can also be retrieved by querying the event table directly instead of using SPCS_GET_METRICS. This requires privileges on the event table, which the DM_MONITOR application role does not grant. For more information, see the official Snowflake documentation.

Backup and restore

Repository backup and restore operations are available only in embedded repository mode.

When using an external repository, backup and recovery must be managed using the capabilities of the database platform hosting the repository.

Create a backup

To create a backup of the embedded repository, run:

CALL <native_app_name>.xdm_public.xdm_repo_backup(<backup_name>);

To ensure the backup operation succeeds, the backup name must follow Snowflake identifier naming rules. It must start with a letter and may contain only letters, numbers, and underscores; spaces, hyphens, and other special characters are not allowed.

For more information, see the official Snowflake documentation.

Restore a backup

To restore a backup of the embedded repository, run:

CALL <native_app_name>.xdm_public.xdm_repo_restore(<backup_name>);

Restoring a backup interrupts the service. The application container is suspended, the volume is restored, and the service is resumed.

Drop obsolete data location tables

The drop_datalocation_tables procedure removes specified tables owned by the Native App from a data location when a model change makes the tables obsolete or requires their recreation.

The drop_datalocation_tables procedure behaves identically in embedded and external repository modes. In both modes, the Native App owns the tables in a data location.

The Native App must retain ownership of data location tables and USAGE on the data location schema to drop the tables:

Do not transfer table ownership to an account role. Snowflake does not allow transferring ownership back to an application, so the Native App permanently loses the ability to manage those tables. The drop_datalocation_tables procedure requires no ownership transfer.
Do not revoke the Native App’s USAGE privilege on the data location schema. Without it, the Native App cannot drop the tables it owns. Account roles do not own those tables and cannot drop them either. The tables remain undroppable until the Native App’s USAGE privilege is restored.

The procedure requires the following:

The XDM_APP application role, granted to the Snowflake role used to call the procedure. To grant that role, run:
```
GRANT APPLICATION ROLE <native_app_name>.XDM_APP TO ROLE <account_role_name>;
```
A warehouse in use in the current session.
The Native App grants on the data location database and schema. For more information, see Prepare Snowflake resources for each datasource.

Drop the tables and redeploy the model

To drop obsolete data location tables:

Identify the tables to drop in the data location schema. For information about the tables created for a model, see Data hub table structures.

Dropping a table is irreversible. Data location tables are Snowflake hybrid tables, which do not support UNDROP or the Snowflake Time Travel feature. All data stored in a dropped table is permanently lost, even when the model change affects only part of the table.

Repository backups created with xdm_repo_backup do not include data location tables.

Call the procedure with the data location database, schema, and an array of table names.

Example

To drop two tables for a Customer entity, run the following call. Replace the database and schema placeholders and the example table names with the values for your data location:

CALL <native_app_name>.xdm_public.drop_datalocation_tables(
    '<data_location_database_name>',
    '<data_location_schema_name>',
    ARRAY_CONSTRUCT('SD_CUSTOMER', 'GD_CUSTOMER')
);

Each database, schema, and table name passed to the procedure must be an unqualified identifier without embedded quotes. Do not include a database or schema qualifier in a name, or pass table names as a comma-separated string instead of an array.
xDM infrastructure tables, whose names start with DL_ or MTA_, cannot be dropped. Naming one rejects the entire call before any table is dropped.
Tables that do not exist or are not owned by the Native App are skipped.
Foreign keys that reference a dropped table from surviving tables are dropped with it. The order of the table names in the array has no effect.

Review the returned report and confirm that the intended tables were dropped. For the report fields and statuses, see Interpret the drop report.
If the intended tables were dropped, redeploy the model edition to the data location. For more information, see Deploy a model edition. Deployment recreates the dropped tables to match the updated model.

Interpret the drop report

The report contains a call-level status, counts, and dropped, skipped, and failed lists. The counts summarize the table results.

Call-level status

The status field has one of the following values:

OK: the requested tables were dropped.
PARTIAL_SUCCESS: at least one table was dropped; the other tables were skipped, and no drop failed. See the skipped list for the reason each table was skipped.
PARTIAL_FAILURE: at least one drop failed during execution; other tables may have been dropped or skipped. See the failed list for the reason each drop failed.
NOTHING_DROPPED: no table was dropped and no drop failed; all tables were skipped. See the skipped and failed lists for the reason each table was skipped or failed.
NOTHING_TO_DO: the table array was empty or NULL; no table was dropped.
REJECTED: the whole call was refused before any table was dropped. The report gives one of the following reasons:
- INVALID_IDENTIFIER: a database, schema, or table name is not an unqualified identifier, or contains embedded quotes. Correct the name and run the procedure again.
- APPLICATION_DATABASE: the database argument targets the Native App’s own database instead of a data location database. Correct the argument and run the procedure again.
- PROTECTED_TABLE: the array includes an infrastructure table whose name starts with DL_ or MTA_. Remove the table from the array and run the procedure again.
- SCHEMA_NOT_ACCESSIBLE: the schema does not exist, or the Native App cannot access it. Check the schema name. If the schema exists, restore the Native App’s grants on the data location, as described in Prepare Snowflake resources for each datasource.

Table results

The dropped, skipped, and failed lists identify the tables and give a reason for each result.

In the skipped list, specifically:

NOT_FOUND means that the table does not exist in the target schema.
NOT_OWNED_BY_APPLICATION means that the table is owned by another role and cannot be dropped by the procedure.

Application lifecycle management

Suspend

To temporarily suspend all containers of the Native App, run:

CALL <native_app_name>.xdm_public.suspend_app();

Resume

To resume the Native App containers, run:

CALL <native_app_name>.xdm_public.resume_app();

Resuming the Native App may upgrade the Native App containers to the latest available version.

Reload

To restart the Native App and apply updated configuration parameters, run:

CALL <native_app_name>.xdm_public.reload_app(<params>);

The reload_app procedure restarts the xDM service, which causes a short service interruption.

The <params> argument is a JSON object (VARIANT) containing configuration keys. For a list of supported parameters and their behavior, see Configure parameters.

When using reload_app, only the provided parameters are updated; all others retain their previously saved values.

Stop

To stop the Native App and destroy all associated containers and volumes, run:

CALL <native_app_name>.xdm_public.stop_app();

In embedded repository mode, this operation permanently deletes all repository data.
In external repository mode, the external database is not affected.

Upgrade the Native App

Patch upgrades of the Native App are handled automatically. Configuration parameters are preserved and reapplied during upgrades.

To apply new configuration parameters outside of an upgrade, reload the Native App, as described in Reload.