# Delivery options

Source: https://developers.novilabs.com/data/delivery/

> Every way to receive Novi UDM Data, who sets each one up, and the exact steps.

Pick how you receive Novi UDM Data and follow its steps. Every path reaches the same database, `NOVI_DATA_ACCESS`, and the same views, so the same SQL works everywhere and reads the latest load. To start, contact your Customer Success Advisor or support@novilabs.com.

## Compare the options

<DeliveryOptions />

| Path | Best for | Who sets it up | How you sign in |
| --- | --- | --- | --- |
| [Reader account](#novi-hosted-reader-account) | Teams without Snowflake | Novi | Personal username and password, role `DATA_READER` |
| [Share into your account](#share-into-your-snowflake-account) | Teams that already use Snowflake | Novi, then your Snowflake administrator runs one script | Your own Snowflake users and roles |
| [SQL over HTTPS](#sql-over-https) | Scripts, apps, and pipelines | Comes with either account | Programmatic access token |
| [BI or lakehouse connection](#connection-for-a-bi-or-lakehouse-tool) [Preview] | Databricks, Tableau, or Power BI with no person logging in | Novi, on request | RSA key pair |
| [Bulk files](#bulk-files) | Loading into your own database | Comes with either account | Query a view for a signed link |
| [Export jobs](#planned-export-jobs) [Planned] | Large extracts without writing SQL | Not available yet | Not available yet |

Every path sees only the basins in your subscription.

## Novi-hosted reader account

Novi hosts a Snowflake account for your team, so you need no Snowflake administrator.

1. Novi gives each person their own login. A welcome email brings a login URL, a username and a temporary password. Change the password at first sign-in.

2. Sign in. Your role is `DATA_READER` and your warehouse `NOVI_WH`.

3. Set the database and schema, then check your session:

   ```sql title="Check your session"
   USE DATABASE NOVI_DATA_ACCESS;
   USE SCHEMA NOVI_WELLS;

   SELECT current_account()   AS account,
          current_role()      AS role,
          current_warehouse() AS warehouse,
          current_database()  AS database,
          current_schema()    AS schema;
   ```

4. Browse **Databases > NOVI_DATA_ACCESS > NOVI_WELLS > Views**, or run a [cookbook recipe](https://developers.novilabs.com/cookbook/).

The welcome email includes the data dictionary and example queries, and, when API access is part of your setup, an API endpoint and a starter token for [SQL over HTTPS](#sql-over-https).

> **Tip:**
> After about a minute idle, the next query takes 10 to 30 seconds to start. The same SQL run again within 24 hours returns at once.

## Share into your Snowflake account

Novi shares the data to your Snowflake account as a private listing. You manage users, roles and warehouses as usual, and pay for the warehouse that runs your queries.

1. Your Snowflake administrator runs this and sends the result to Novi:

   ```sql title="Identify your account"
   SELECT
       CURRENT_ORGANIZATION_NAME() || '.' || CURRENT_ACCOUNT_NAME() AS org_account_name,
       CURRENT_ACCOUNT()                                            AS account_locator,
       CURRENT_REGION()                                             AS region;
   ```

2. Novi emails your technical contacts a setup script, `novi_setup.sql`.

3. Your administrator opens a worksheet as `ACCOUNTADMIN`, pastes the script, replaces placeholders such as `YOUR_USERNAME`, and runs it.

4. Run the script's verification step as the new user. Each product returns a row count.

The listing also appears in Snowsight under **Data sharing > External sharing > Shared with you**; **Get** there does the script's first step.

| Step | Statement | Effect |
| --- | --- | --- |
| 1 | `CREATE DATABASE NOVI_DATA_ACCESS FROM LISTING '...'` | Adds the listing as a database |
| 2 | `CREATE WAREHOUSE IF NOT EXISTS ...` | Creates a warehouse. Skip it if you have one |
| 3 | `CREATE ROLE IF NOT EXISTS ...` and `GRANT USAGE ON WAREHOUSE` | Creates a role that can use the warehouse |
| 4 | `GRANT IMPORTED PRIVILEGES ON DATABASE NOVI_DATA_ACCESS TO ROLE ...` | Lets the role read the views |
| 5 | `CREATE USER IF NOT EXISTS YOUR_USERNAME ...` and `GRANT ROLE` | Creates a user with the role, or grant it to an existing user |
| 5b | `ALTER USER YOUR_USERNAME ADD PROGRAMMATIC ACCESS TOKEN ...` | Optional. A token for [SQL over HTTPS](#sql-over-https) |
| 6 | `SELECT COUNT(*) FROM NOVI_WELLS.WELL` | Verifies access |

If a role gets a permission error on a view, grant it `DR_WELLS_STANDARD` or `DR_WELLS_FULL`, Novi's database roles in `NOVI_DATA_ACCESS`.

> **Caution:**
> Outside AWS us-east-2, the listing can take a few hours to appear the first time. If `CREATE DATABASE` fails, wait and run the script again.

## SQL over HTTPS

Send SQL to Snowflake's SQL API and get JSON back, from either account type.

- **Endpoint:** your account URL followed by `/api/v2/statements`, shown in your welcome email.
- **Token:** a programmatic access token, sent as a bearer token.
- **Body:** JSON with `statement`, `warehouse`, and `database`. On your own account, use your warehouse name.

  **macOS and Linux**

```bash title="Run a query"
curl -X POST "$NOVI_SNOWFLAKE_URL/api/v2/statements" \
  -H "Authorization: Bearer $NOVI_SNOWFLAKE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"statement": "SELECT WELL_KEY, WELL_NAME, BASIN, STATE, COUNTY, STATUS FROM NOVI_WELLS.WELL LIMIT 100", "warehouse": "NOVI_WH", "database": "NOVI_DATA_ACCESS"}'
```

  
  **Windows Command Prompt**

```bat title="Run a query"
curl -X POST "%NOVI_SNOWFLAKE_URL%/api/v2/statements" -H "Authorization: Bearer %NOVI_SNOWFLAKE_TOKEN%" -H "Content-Type: application/json" -d "{\"statement\": \"SELECT COUNT(*) FROM NOVI_WELLS.WELL\", \"warehouse\": \"NOVI_WH\", \"database\": \"NOVI_DATA_ACCESS\"}"
```

  

A successful call returns a `data` array of rows and the message `Statement executed successfully.` Full API: docs.snowflake.com/en/developer-guide/sql-api/guide.

### Replace the starter token

The reader-account starter token is short-lived. Replace it with a one-year token under the same name, using the name and role from your welcome email:

```sql title="Rotate your token"
ALTER USER REMOVE PROGRAMMATIC ACCESS TOKEN novi_api;
ALTER USER ADD PROGRAMMATIC ACCESS TOKEN novi_api
    ROLE_RESTRICTION = 'DATA_READER'
    DAYS_TO_EXPIRY = 365;
```

Save the token output at once: it cannot be shown again.

## Connection for a BI or lakehouse tool

[Preview]

For a tool with no person logging in, Novi creates one machine user in a Novi-hosted account, on request. One email brings the connection details (host, port 443, user, role, warehouse, database, key fingerprint) and a private key link that works for 72 hours. Novi keeps no copy. The key works while your subscription is active.

| Tool | How to connect |
| --- | --- |
| Databricks | In Catalog Explorer, create a Snowflake connection with auth type PEM Private Key and paste the flattened key file. Then create a foreign catalog on `NOVI_DATA_ACCESS`. Needs Unity Catalog and a SQL warehouse |
| Tableau | Snowflake, key-pair authentication, the `.p8` file |
| Power BI | Get data, Snowflake, key-pair authentication, the `.p8` file |

Statements on this connection stop after 2 hours.

## Bulk files

Download zips to load into your own systems. Novi builds a new set every weekday; two views list the links.

- **Full zips:** one per basin in your subscription, plus a USA zip if you have every US basin. Each holds the reference lists too.
- **Diff zips:** the changes from one run to the next.

1. List your full zips:

   ```sql title="Full zips"
   SELECT BASIN, ZIP_NAME, RUN_ID, RUN_AT_UTC, ZIP_SIZE_MB, URL
   FROM NOVI_WELLS.DOWNLOADS_FULL
   ORDER BY BASIN;
   ```

2. Download and load a zip. Its `RUN_ID` is the run you hold.

3. List the newer diffs, oldest first:

   ```sql title="Diffs to apply"
   SELECT DAYS_PRIOR, BASE_RUN_ID, RUN_ID, ZIP_SIZE_MB, URL
   FROM NOVI_WELLS.DOWNLOADS_DIFF
   WHERE BASIN = 'Permian'
     AND RUN_ID > '20261016_171714'
   ORDER BY RUN_ID;
   ```

4. Apply each diff in `RUN_ID` order, only if its `BASE_RUN_ID` is the run you hold. You then hold its `RUN_ID`.

Each link works for 2 hours; a started download continues. Anyone with a link can use it, so do not share it.

| In a zip | What it is |
| --- | --- |
| File name | The run, for example `Permian_20261016_171714.zip` |
| `Database/` | One tab-separated file per base view, with a header row, in title case: `Database/Well.tsv`, `Database/Well_Completion.tsv` |
| Not included | `WELL_PERMIT`, `WELL_PRODUCTION_SUMMARY`, `OPERATOR_CONTACT` and the presentation views. Query them in Snowflake |
| `Shapefiles/` | Full zips of basins with acreage data: company acreage polygons in WGS84 (EPSG:4326), per operator in `Shapefiles/<Operator>/` and for all in `Shapefiles/All/` |
| `Database/<Table>--deleted.tsv` | Diff zips: key columns of rows to delete. Apply first |
| `Database/<Table>--diff.tsv` | Diff zips: full rows to insert or replace, on the same keys |
| `Database/<Table>.tsv` in a diff | Replaces your whole copy of that table, for example after a column change |

`DOWNLOADS_DIFF` keeps the last 7 runs. If the next diff's `BASE_RUN_ID` is not the run you hold, download the full zip again. `DAYS_PRIOR` counts runs, not days. Novi does not yet email you when new files are ready: check the views.

## Planned: export jobs

[Planned]

Send a filter or area of interest and get a short-lived download link to the same data.

## Not offered

Direct reads of Novi's storage from Spark, Trino, or other engines. Use the [BI or lakehouse connection](#connection-for-a-bi-or-lakehouse-tool) or [bulk files](#bulk-files).
