Overview

Ternary's Bring Your Own Data (BYOD) feature allows you to ingest custom time‑series datasets into the Ternary platform. This is useful for uploading business KPIs, non‑cloud costs, or any other metrics that you want to analyze alongside your existing multi‑cloud integrations or cloud bills. Examples of data you may want to upload include: data center spend, private cloud costs, SaaS spend, or revenue data.

The Ternary BYOD integration supports four data sources:

• Amazon S3 — upload a CSV file into an S3 bucket.
• Microsoft Azure Blob Storage — upload a CSV file into a Blob container.
• Google Cloud Storage (GCS) — upload a CSV file into a GCS bucket.
• Google BigQuery table — ingest data directly from a BigQuery table.

Ternary checks for changes every four hours, if a change is identified we will update your BYOD data. Admins can also trigger a manual refresh from the integration settings.

Requirements:

• Your dataset must contain at least one column with a date or timestamp that represents the start of the billing or usage period. This date field is used for normalization and ingest scheduling. Additional date or timestamp columns are optional but provide more granular analysis.
• Supported formats:
  • CSV files for S3, Azure Blob Storage, and GCS sources.
  • Native BigQuery tables for GCP.
• You may store data in the same bucket/folder as your detailed billing files or in a separate location. Extra IAM permissions are needed if using a different bucket.

Supported Tag Formats

• Single key–value columns: separate columns per tag (e.g., a column named environment with values prod, dev, etc.). Each column header represents the tag key, and each row’s value becomes the tag value.
• JSON tag columns: a single column containing a JSON object or list of key–value pairs. Ternary flattens these automatically into individual tags/dimensions.

Prerequisites

Before you start, ensure:

1. Appropriate IAM permissions are configured for Ternary’s service account to read your data source.
   • For AWS S3: ensure the role used for Cost & Usage Reports also has access to your BYOD bucket/folder.
   • For Azure Blob Storage: grant Storage Blob Data Reader on the container.
   • For GCS: grant permissions such as storage.objects.get, storage.objects.list, resourcemanager.projects.get, etc.
   • For BigQuery: Ternary uses its existing service account; you must grant bigquery.tables.getData on the target table.
2. Data schema includes at least one date or timestamp field. This will be mapped to Charge Period Start.
3. Integration name cannot contain spaces. Use underscores or hyphens (e.g., BYOD_test).

Step‑by‑Step Setup

1. Navigate to BYOD configuration

1. Sign in to Ternary as an Admin and go to Admin → Integrations.
2. Click New Integration and choose Bring Your Own from the drop‑down.

2. Select Configuration

You will see a three‑step wizard:

1. Select Configuration (choose your storage provider and enter connection details).
2. Table Assignment (map your columns to Multi‑Cloud fields or create new metrics/dimensions).
3. Submit.

a. Choose your data source

Four buttons let you pick Amazon S3, Azure Blob Storage, Google Cloud Storage, or Google BigQuery. Click the provider where your CSV or table resides.

b. Enter integration details

The form fields change based on your selection. For Google Cloud Storage, you’ll see:

• Name (required) — no spaces; use something descriptive like BYOD_test.
• Storage URI (required) — full bucket path, e.g., gs://byod-dogfooding/saas-billing.
• A permissions call‑out listing required IAM permissions for GCS.

For S3 and Azure Blob Storage, the form similarly asks for a bucket URI and may include a Role ARN or Azure connection string.

For BigQuery, you’ll be asked for a Table Path (in project.dataset.table format). Since BigQuery tables are used for GCP billing by default, using BYOD with BigQuery usually requires additional permissioning.

c. Preview the data

Under Data Source Validation, click Preview. Ternary loads a sample of your data, detects the columns, and shows a preview table. A green message will confirm a successful preview and tell you how many columns were detected.

You must preview before moving to the next step.

Click Next to continue.

3. Table Assignment

In this step, you map your CSV/BigQuery columns to Ternary’s Multi‑Cloud fields or create new dimensions/measures. The page consists of:

• Select Charge Period Start Column — choose the column representing the start date of each charge period. This is required for normalization. Ternary shows available date columns (e.g., billingperiodstart and billingperiodend). Choose the one that corresponds to the start date (often billingperiodstart).

• Assignments Table — lists each uploaded column with sample data and a status (Pending, Assigned). For each column, you have three options:
  1. Assign to an existing Multi‑Cloud field. Use this to map known fields like BillingPeriodEnd, ServiceName, AccountId, etc. When you select a Multi‑Cloud field, the column’s values will be displayed in reports using Ternary’s canonical field name.
  2. Create a new grouping/dimension. This treats the column as a dimension unique to your data. You must specify the dimension type:
     • String grouping — the column is treated as a categorical value.
     • Tag (JSON) — select this if the column contains a JSON object or list of tag key–value pairs; Ternary will flatten it into individual tags.
     • Timestamp — use this if the column contains dates or date‑time values besides the charge period start; this allows additional time‑based analyses.
       New dimensions inherit the column header as their name in Ternary. To change the name, edit the header in your source file before re‑ingesting.
  3. Create a new measure. This treats the column as a numeric metric (e.g., effectivecost, discount_amount, usage_units). As with dimensions, new measures keep the exact column header as their name in Ternary. - Note measures always aggregate by SUM. For non-additive values (like IPs or hardware specs), use a dimension instead.

You can use Apply All Suggestions to auto‑map columns based on name and data type, or Reset All to clear mappings. The Assignment Progress bar shows how many columns you’ve mapped; all required fields must be assigned before you can continue.

After completing your assignments, click Next.

4. Submit

The final step is a confirmation screen where you review your configuration:

• Integration name and source location.
• A summary table of your column mappings (showing which fields will map to existing Multi‑Cloud fields, which will be new dimensions, and which will be new measures).
• Ingestion schedule (every four hours).
• A button to request an immediate ingest (“Request Billing Update”).

If everything looks correct, click Submit to create the integration. Ternary then ingests the data on the four‑hour schedule (or immediately if you trigger a manual update).

Using BYOD Data in Reports

Once ingested, your BYOD dataset appears as a new provider in the Reporting Engine (e.g., under “Custom Data”). You can:

• Combine BYOD metrics with other providers in the same report.
• Group by your custom dimensions or tags.
• Create custom dashboards to analyze KPIs alongside cloud spend.

BYOD data follows the same ingestion frequency as billing data (every four hours). If you need immediate updates, click the gear icon on the integration and select Request Billing Update to bypass the wait.

Troubleshooting & Common Errors

FAQ

• Can I load non‑cost metrics like headcount or usage units?
  Yes. BYOD accepts any time‑series numeric measures. You can create new measures during the Assignment step and analyze them alongside cost data.

• Can I mix BYOD data with my cloud billing data?
  Absolutely. BYOD data appears as an additional provider. Reports can group by provider, account, or any dimensions across providers.

• How often is BYOD data refreshed?
  Every four hours by default. Admins can trigger a refresh manually via the integration’s settings.

• Do I need separate IAM permissions if I store the file in the same bucket as my billing data?
  If the BYOD file resides in the same bucket/container as your billing files (but in a different folder), you can reuse the existing role. If it’s a different bucket or project, update the role to include read access.

• What happens if I change the schema (add/remove columns) later?
  If new columns appear, you’ll need to revisit Table Assignment to map them. Removed columns will no longer be ingested. Changing the date column requires reconfiguring the integration.

• Can I delete a BYOD dataset?
  Yes. You can delete the integration from the Admin → Integrations page. Deleting it stops ingestion and removes the data from reporting.

• What tag formats are supported?
  You can provide tags either as individual key–value columns or as a JSON tag column. Ternary auto‑flattens the JSON list into separate dimensions.

• Is there a maximum number of columns?
  While there’s no hard limit, extremely wide tables may be harder to map. Only columns you map will be ingested; unmapped ones are ignored.