Vayu Docs

Vayu Snowflake

The Snowflake integration lets Vayu read usage events straight from a table or view in your Snowflake account. Your usage data stays in Snowflake. Vayu queries the table once a day for new rows and turns each row into a usage event for billing.

This page covers what you need before you start, how to prepare the table, what goes into the connection, and how syncing works.

Snowflake can't be connected from the Integrations page yet. Send the details listed under Connection fields to your Vayu contact, and the Vayu team sets up the connection for you.

How It Works

Vayu connects to Snowflake with a username and password.
On each run, Vayu queries the table for rows whose updated_at column is newer than the last row it imported. To give late writes time to land, each run stops 5 minutes before the current time.
Each row becomes one event. The required columns map to the event's fields, and every other column is stored in the event's data.
The first run starts from the Import from date. If none is set, Vayu starts one day back.

Before You Start

Make sure you have, or can create, the following in Snowflake:

Account identifier: your Snowflake account, for example myorg-myaccount.
A user for Vayu with a password. Vayu only supports username and password sign-in for Snowflake.
A warehouse the user can run queries on.
The database and schema that hold the usage table.
A table or view with one row per usage event and the required columns.
A role (optional) with the grants below. If you don't set one, Vayu uses the user's default role.

The role Vayu uses needs read-only access:

CREATE ROLE vayu_reader;
GRANT USAGE ON WAREHOUSE my_warehouse TO ROLE vayu_reader;
GRANT USAGE ON DATABASE billing TO ROLE vayu_reader;
GRANT USAGE ON SCHEMA billing.usage TO ROLE vayu_reader;
GRANT SELECT ON TABLE billing.usage.usage_events TO ROLE vayu_reader;
-- For a view, use: GRANT SELECT ON VIEW billing.usage.usage_events_v TO ROLE vayu_reader;

CREATE USER vayu_user PASSWORD = '<strong password>' DEFAULT_ROLE = vayu_reader DEFAULT_WAREHOUSE = my_warehouse;
GRANT ROLE vayu_reader TO USER vayu_user;

Required Table Columns

The table or view must have these columns, named exactly as shown:

Column	Type	Maps to
`ref`	VARCHAR	The event's unique reference. Use a stable ID so the same row is never billed twice.
`timestamp`	TIMESTAMP_NTZ, in UTC	When the event happened.
`customerAlias`	VARCHAR	The customer the event belongs to. It must match the customer's alias in Vayu.
`name`	VARCHAR	The event name, for example `api_call`.

Any other column, such as quantity or region, is copied into the event's data and can be used in your metering rules.

The table also needs an updated_at column: a TIMESTAMP_NTZ column, in UTC, that records when each row was added or last changed. Vayu uses it to find new rows on each run. It's separate from timestamp, which is when the event happened, and like any other extra column it's also copied into the event's data. You can name it anything; you tell Vayu its name in the connection fields.

Create the columns with double-quoted names in the exact case shown, for example "customerAlias". Vayu reads the columns by these exact names. Snowflake stores unquoted names in uppercase, so quoting keeps the case intact.

CREATE TABLE billing.usage.usage_events (
  "ref" VARCHAR NOT NULL,
  "timestamp" TIMESTAMP_NTZ NOT NULL,
  "customerAlias" VARCHAR NOT NULL,
  "name" VARCHAR NOT NULL,
  "quantity" NUMBER,
  "updated_at" TIMESTAMP_NTZ NOT NULL
);

If your raw data uses different column names, create a view that renames them rather than changing the source table:

CREATE VIEW billing.usage.usage_events_v AS
SELECT
  event_id      AS "ref",
  event_time    AS "timestamp",
  account_slug  AS "customerAlias",
  event_type    AS "name",
  units         AS "quantity",
  loaded_at     AS "updated_at"
FROM billing.raw.events;

Vayu compares timestamps as TIMESTAMP_NTZ in UTC, so store event times and updated_at values in UTC.

Connection Fields

These are the details the Vayu team needs to set up the connection.

Credentials

Field	Required	Description
Account	Yes	Your Snowflake account identifier.
Username	Yes	The Snowflake user Vayu signs in as.
Password	Yes	That user's password.
Warehouse	Yes	The warehouse that runs Vayu's queries.
Database	Yes	The database that holds the table.
Schema	Yes	The schema that holds the table.
Role	No	The role to use. Defaults to the user's default role.
Region	No	The account's region, if your account identifier needs one.

Source

Field	Required	Description
Table	Yes	The table or view to read, for example `usage_events`. A bare name is looked up in the database and schema above. You can also give the full path, `DATABASE.SCHEMA.TABLE`.
`updated_at` column	Yes	The column that tracks when each row was added or changed, for example `"updated_at"`. Vayu uses it to find new rows. Include the double quotes if the column name is quoted.
Import from	No	The date the first import starts from. It only applies before the first run.
Auto-import events	No	Turn on to import new rows once a day. It's off unless you ask for it.

The password is a credential. Share it with Vayu through a secure channel, not in plain email or chat.

How Syncing Works

Scheduled imports. When auto-import is on, Vayu imports once a day. Each run picks up where the last one stopped: from the last imported row's updated_at value up to 5 minutes before the run started. Rows are read in updated_at order.
Late rows. A row whose updated_at value is older than the last imported row's isn't picked up by scheduled runs. Use a manual run to import it.
Long runs. If a run has a lot of rows, it stops after about four minutes and the next run continues from where it stopped.
Manual runs. On Data metering → Events, click Manual run to import rows whose updated_at falls in a date range of up to 31 days (UTC). It runs in the background, one run per day. Existing events are updated, not duplicated. Last polled shows the updated_at value scheduled imports have reached (in UTC).

A manual run can recalculate invoices, so usage on them may change. Approved invoices and manually edited measurements stay the same.

Check Your Events

Imported rows appear under Data metering → Events after the next run. Each event shows the ref, name and customerAlias from its row, with the extra columns under Data.

If events don't show up, check that:

The rows' updated_at values are after the Import from date and more than 5 minutes old.
The column names are quoted and match the required columns exactly.
Each customerAlias matches a customer in Vayu.
The role has USAGE on the warehouse, database and schema, and SELECT on the table or view.

Pushing Events Instead

If you'd rather control when and how data leaves Snowflake, you can skip this integration and send events from your own pipeline to the Vayu events API. See Sending events.

Snowflake