Skip to main content

Documentation index: llms.txt. This page is also available as markdown: append .md to this URL or send Accept: text/markdown.

Provide Access to Your LookML

Catalog reads your LookML in one of two ways. Use the one that fits your Git setup:

Grant Catalog Access to Your Git Repos (Read-Only)​

Catalog reads every LookML project you use, so repeat the steps below for each Git repository backing one of your Looker projects.

1. Send to the Catalog Team the SSH URL of Each Repo​

  • GitHub: You can find it by clicking Clone on your GitHub Looker repo.
  • GitLab: You can find it by clicking Code on your GitLab Looker repo.

2. Add the Deploy Key to Each Repo​

In return, Catalog will provide you with a deploy key.

  • GitHub: You can add it to your repo via Settings > Security > Deploy keys.
  • GitLab: You can add it to your repo via Settings > Repository > Deploy keys.

Send an Archive of Each Repo​

Use this option when you can't add a deploy key to your repos.

1. Get What You Need​

2. Prepare One Archive per Looker Project​

Each archive must:

  • Be a zip or a gzip-compressed tar file. Catalog reads the format from the file content, so the file name and extension don't matter.
  • Hold the whole repo, at its top level or inside a single folder.
  • Hold at least one .lkml file.

The archive your Git host produces when you download a branch meets these rules. The .git folder isn't needed.

3. Upload Each Archive​

Run one command per archive:

castor-upload -k <token> -s <source_id> -z <zone> -t LOOKML --project_name <project_name> -f <archive>
  • -k, --token: your Catalog API token.
  • -s, --source_id: the source ID of your Looker integration.
  • -z, --zone: US if your instance is on app.us.castordoc.com, EU if it's on app.castordoc.com. Defaults to EU.
  • -t, --file_type: LOOKML.
  • --project_name: the Looker project the archive holds.
  • -f, --file_path: the archive. -d, --directory_path isn't supported with LOOKML.

You can set CASTOR_UPLOADER_TOKEN, CASTOR_UPLOADER_SOURCE_ID, CASTOR_UPLOADER_ZONE and CASTOR_UPLOADER_PROJECT_NAME instead of the matching arguments.

If you push your Looker extraction files yourself, schedule these uploads with them.

Upload Every Project Each Time

When a sync receives archives, it replaces your LookML with them. A project left out of that upload loses its lineage until its next archive arrives.

When an Archive Is Refused​

A sync refuses an archive when:

  • Its project isn't a Looker project of your source.
  • It isn't a zip or a gzip-compressed tar, or it can't be read.
  • It holds a file outside the repo, with an absolute path or ...
  • It holds no .lkml file.

When one archive is refused, the sync reads none of the archives it received, and Catalog keeps your previous LookML lineage. Coalesce Support tells you which archive was refused and why. Fix it, then upload every project again.