Skip to main content
Unlisted page
This page is unlisted. Search engines will not index it, and only users having a direct link can access it.

Mode

Connect Mode Analytics to Coalesce Catalog using Catalog-managed credentials or the client-managed extractor and upload flow.

Requirements​

Warehouse Integration Required

A Warehouse type integration must already be configured to complete the first ingestion of this integration.

To use Mode with Catalog, you need:

Catalog Managed​

Send the API key details through Safenote with Slack or email.

For your first sync, it can take up to 48 hours before ingestion completes. Catalog notifies you when it finishes.

If you prefer not to share credentials with Catalog, continue to Client Managed.

Client Managed​

Doing a One Shot Extract​

For your trial, you can give us a one-shot view of your BI tools.

To get things working quickly, here is a Google Colab notebook to run the package.

Running the Extraction Package​

Install the PyPI Package​

pip install castor-extractor[mode]

For further details, see the castor-extractor PyPI page.

Run the Package​

Once the package has been installed, you should be able to run the following command in your terminal:

castor-extract-mode [arguments]

The script will run and display logs as following:

INFO - Authentication succeeded.
INFO - Starting extraction for DATASOURCE...
INFO - Calling https://modeanalytics.com/api/...
INFO - 1 rows extracted
INFO - Wrote output file: /tmp/catalog/1649080890-datasource.json
INFO - Starting extraction for COLLECTION...


...

INFO - Wrote output file: /tmp/catalog/1649080890-member.json
INFO - Wrote output file: /tmp/catalog/1649080890-summary.json

Credentials​

  • -H, --host: the host name or IP address where your Mode Analytics instance runs. If you use Mode's managed cloud, use https://modeanalytics.com.

  • -w, --workspace: The name of your workspace. More information in the Mode organizations documentation

  • -t, --token: The Token value from the API token created in Mode.

  • -s, --secret: The Password value from the API token created in Mode.

Optional Arguments​

  • -o, --output: target folder to store the extracted files

Run any extractor command with --help to print the full argument list.

Use ENV Variables​

If you don't want to specify arguments every time, you can set the following ENV in your .bashrc:

CASTOR_MODE_ANALYTICS_HOST
CASTOR_MODE_ANALYTICS_WORKSPACE
CASTOR_MODE_ANALYTICS_TOKEN
CASTOR_MODE_ANALYTICS_SECRET

CASTOR_OUTPUT_DIRECTORY

Then the script can be executed without any arguments:

castor-extract-mode

It can also be executed with partial arguments (the script looks in your ENV as a fallback):

castor-extract-mode --output /tmp/catalog

Scheduling and Push to Catalog​

When moving out of trial, you'll want to refresh your Mode content in Catalog. Here is how to do it:

The Catalog team will provide you with

  1. Catalog Identifier (an id for us to match your Mode files with your Catalog instance)
  2. Catalog Token An API Token

You can then use the castor-upload command:

castor-upload [arguments]

Arguments​

  • -k, --token: Token provided by Catalog
  • -s, --source_id: account id provided by Catalog
  • -t, --file_type: source type to upload. Currently supported are 0

Target Files​

To specify the target files, provide one of the following:

  • -f, --file_path: to push a single file

or

  • -d, --directory_path: to push several files at once (*)
Directory Contents

(*) The tool will upload all files included in the given directory.

Make sure it contains only the extracted files before pushing.

Then you will need to schedule the script run and the push to Catalog. Use your preferred scheduler to create this job.

Troubleshooting​

Use these steps when Mode ingestion or uploads fail before Mode assets appear in Catalog.

Authentication Succeeds in Logs but Catalog Stays Empty​

Large Mode organizations span multiple workspaces or collections. Extractors may finish without pushing files if upload arguments omit required identifiers.

Resolution:

  1. Confirm castor-upload runs with the source_id and token Catalog operations issued for Mode.
  2. Verify the upload directory contains the JSON outputs listed in extractor logs before each scheduled push.

Wrong Host Value for Managed Mode Analytics​

Managed tenants should target Mode's SaaS hostname while self-hosted installs need your private host.

Resolution:

  1. Use https://modeanalytics.com when your contract references Mode's managed cloud.
  2. Replace host names after DNS or TLS migrations so extractor scripts match the endpoint analysts use in browsers.

API Token Rejected After Rotation​

Mode invalidates older tokens when admins rotate secrets.

Resolution:

  1. Generate a fresh token per Mode API token instructions.
  2. Update Catalog-managed credentials or extractor CLI arguments the same day you revoke the prior token.

Warehouse Prerequisite Missing​

Mode lineage depends on warehouse integrations Catalog already ingested.

Resolution:

  1. Finish configuring the Warehouse integration referenced under Requirements before expecting cross-tool lineage.
  2. Re-run Mode extraction after warehouse assets finish indexing.

Scheduled Jobs Overlap​

Overlapping runs can leave half-written JSON files in the upload folder.

Resolution:

  1. Add file locks or stagger schedules so castor-upload starts only after castor-extract-mode exits cleanly.
  2. Clear stale artifacts before each upload when troubleshooting failures.