deepline-analytics

Files (2)

• SKILL.md
• skill-metadata.json

SKILL.md (first lines)

# Deepline Analytics

## Quick Start

```bash
npm install -g deepline
deepline -h
```

## CLI resolution

Run `deepline` when it is available. If the shell reports that command is missing, use `<workspace-root>/.deepline/runtime/bin/deepline` (or the npm-created `.cmd` shim on Windows). If neither exists, follow `https://code.deepline.com/INSTALL.md` to set up Deepline.

Use this skill to answer customer analytics questions through Deepline's warehouse and semantic-layer tools. The goal is not just to run SQL; it is to preserve the customer's business definitions by starting from the semantic layer, validating the query path, and reporting exactly what metric definitions and filters were used.

## Before You Start

Use `deepline-gtm` instead for prospecting, enrichment, contact finding, outbound sequencing, personalization, or row-by-row lead/account research. Analytics questions ask about existing customer data: revenue, pipeline, funnel, conversion, retention, usage, calls, accounts, opportunities, or warehouse tables.

If Snowflake credentials or a semantic layer are missing, stop and report the setup blocker. Do not guess table names or fall straight to raw SQL; both usually produce incorrect business definitions.

## Deepline Internal Analytics Sources

For Deepline's own product, usage, and operational analytics, choose the source by question. Do not assume every Snowflake metric is dbt-modeled.

| Source                            | Tables / dataset                                                                                                                            | Use for                                                                                                | Caveats                                                                                                                                          |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| Convex replica raw ledger         | `AERO_DB.CONVEX_RAW.*`, especially `PLAY_RUNS` and `INGESTION_PLANES`                                                                       | Persisted app state, play-run status, prebuilt/custom play identity, customer database inventory/state | Authoritative historically, but can lag same-day activity. Raw tables may include sensitive app/customer fields.                                 |
| Convex replica reporting views    | `AERO_DB.CONVEX.USAGE_EVENTS`, `BA_USER`, `BA_MEMBER`                                                                                       | Tool/enrich calls, Deepline credits, user/org identity                                                 | `USAGE_EVENTS` is the primitive billing/usage ledger. Never expose provider spend. Some views are published selectively; verify freshness first. |
| Axiom production logs             | Dataset `vercel`                                                                                                                            | Real-time play/run failures, CLI outcomes, provider/tool errors, log-message failure classes           | Log-shaped. Deduplicate run/request ids and compare against Snowflake when accuracy matters.                                                     |
| RudderStack product events        | `RUDDERSTACK.EVENTS.*` (`TRACKS`, `PAGES`, `IDENTIFIES`, event tables)                                                                      | Product journey, page views, signup/auth lifecycle, attribution                                        | Not the operational ledger. Some browser events may be missing from Snowflake.                                                                   |
| dbt / transformed analytics marts | `AERO_DB.ANALYTICS*` schemas, for example `ANALYTICS.FCT_CUSTOMER_JOURNEY`, `DIM_ACCOUNT`, `CUSTOMER_STREAM`, and dbt views such as `STG_*` | Modeled business metrics: GTM, customer journey, CRM, TAM                                              | Not the default source for play-runtime health unless a modeled table is explicitly known to cover it.                                           |

Current product usage dashboard source of truth:

- Play runs: Snowflake `AERO_DB.CONVEX_RAW.PLAY_RUNS` plus Axiom `vercel` logs with `[sdk-cli-observability] kind: 'play_run_completed'` and `[cli-failure-report] failure_kind: 'play_run_failed'`.
- Legacy workflow runs: Snowflake `AERO_DB.CONVEX_RAW.WORKFLOW_RUNS` joined to `AERO_DB.CONVEX_RAW.WORKFLOWS`.
- Tool/enrich calls: Snowflake `AERO_DB.CONVEX.USAGE_EVENTS` plus Axiom `vercel` logs with `[integrations.execute.outcome]`.
- User/org dimensions and internal filters: prefer Snowflake `AERO_DB.CONVEX_RAW.BA_USER` and `AERO_DB.CONVEX_RAW.BA_MEMBER` for freshness; use reporting views only after checking freshness.
- Customer database: Snowflake `AERO_DB.CONVEX.USAGE_EVENTS` for customer-db usage and `AERO_DB.CONVEX_RAW.INGESTION_PLANES` for table/plane inventory.

That dashboard does not use `AERO_DB.ANALYTICS*` dbt/transformed models. If you add dbt-modeled metrics, document the model names, freshness, and grain next to the raw/Axiom parity metric.

## Decision Matrix

| User asks...                                   | Job                  | Start with                                                                                            |
| ---------------------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------- |
| "What is total pipeline by quarter?"           | Metric breakdown     | `snowflake_get_semantic_layer`, then `snowflake_run_semantic_query`                                   |
| "Break revenue down by product/month"          | Dimensional analysis | Inspect semantic tables for revenue metrics and time dimensions                                       |
| "How many opportunities / accounts / calls..." | Simple count metric  | Find the semantic count metric before writing SQL                                                     |
| "Why does this number look wrong?"             | Debug/validation     | Run semantic query, inspect returned SQL, then compare with raw SQL only if needed                    |
| "Query this specific warehouse table"          | SQL fallback         | Check whether it is represented in the semantic layer; otherwise use `snowflake_run_query`            |
| "Upload/edit/read the semantic layer"          | Admin setup          | Use `snowflake_update_semantic_layer` / `snowflake_get_semantic_layer`, then return here for querying |

## Standard Loop

`snowflake_get_semantic_layer` and `snowflake_run_semantic_query` are Deepline tool IDs invoked with `deepline tools execute ...`; do not search for MCP/deferred tool names first.

1. **Confirm workspace context.** If the result depends on customer setup, run `deepline auth status` to see which workspace receives the query.
2. **Inspect the semantic layer.** Run `deepline tools execute snowflake_get_semantic_layer ...` before constructing payloads: `includeYaml: false` for a quick table list, `includeYaml: true` when choosing exact metrics, dimensions, or filters.
3. **Map the user's words to semantic objects.** Choose one semantic `table_name`, named `metrics`, named `dimensions` or `time_dimensions`, and named `filters` from the YAML. Do not invent them.
4. **Pilot the smallest useful query.** One metric and a low `rowLimit`, for example `{"type": "metrics", "params": {"table_name": "OPPORTUNITY", "metrics": ["num_opportunities"]}, "rowLimit": 1}`; expand after it succeeds. This cheaply catches missing credentials, missing semantic objects, and warehouse schema drift.
5. **Inspect returned SQL and rows.** `snowflake_run_semantic_query` returns result rows and the rendered SQL. The SQL is the audit trail and the safest starting point for a raw-SQL fallback.
6. **Answer in business terms.** Name the metric, grouping dimensions, filters/base filters, row limits, and caveats. If the tool says results were limited, say so.

## Fastest Metric Path

For a customer metric question where the semantic table is knowable from the wording, use this exact CLI path. Do not call ToolSearch, look for MCP tools, or write raw SQL first.

1. Confirm the workspace: `deepline auth status`.
2. Read the semantic layer: `deepline tools execute snowflake_get_semantic_layer --payload '{"includeYaml": true}'`.
3. Run the semantic query with both the user-facing label and the sortable date-start dimension. For other metrics, replace only `table_name`, `metrics`, and dimensions after confirming names in the semantic layer.

   ```bash
   deepline tools execute snowflake_run_semantic_query --payload '{
     "type": "metrics",
     "params": {
       "table_name": "OPPORTUNITY",
       "metrics": ["total_pipeline_generated"],
       "dimensions": ["discovery_quarter_label", "discovery_quarter_start"]
     },
     "rowLimit": 100
   }'
   ```

4. Read the result rows directly from the response. Select latest periods by sorting `DISCOVERY_QUARTER_START` descending; `rowLimit` is not ordering. Do not chase `extracted_csv` files, shell-sort CSV artifacts, or rerun the semantic query unless the response is unavailable.
5. Do not open saved transcript files, `tool-results/*.txt`, or full semantic-layer blobs with `Read`, `cat`, or ad hoc Python just to confirm names; large semantic YAML can exceed tool read limits. Use the current command output, targeted text search, or rerun with `includeYaml: false` for a table list before requesting full YAML.

## Semantic Query Contract

Use the typed metrics payload by default:

```json
{
  "type": "metrics",
  "params": {
    "table_name": "OPPORTUNITY",
    "metrics": ["num_opportunities"],
    "dimensions": ["close_quarter_label"],
    "filters": ["exclude_renewal_opportunities"]
  },
  "rowLimit": 100
}
```

The legacy flat metrics form is also accepted when needed: the `params` fields at the top level with no `type`, for example `{"table_name": "OPPORTUNITY", "metrics": ["num_opportunities"], "dimensions": ["close_quarter_label"], "rowLimit": 100}`.

### Allowed Concepts

- `table_name` is a semantic table name from the YAML, not the model root name and not necessarily the physical Snowflake table.
- `metrics` are aggregate business definitions. Use them for reported numbers.
- `dimensions` and `time_dimensions` group the metric. Use semantic names, not raw SQL expressions.
- `facts` are row-level values: useful for detail extracts, usually wrong for aggregate reports.
- `filters` are named semantic filters from the YAML.
- `rowLimit` limits returned rows. Use low limits for pilots and larger limits only after the payload is correct.

### Latest Periods Are Not Row Limits

Do not use `rowLimit: 5` to answer "last 5 quarters", "latest 12 months", or similar questions. Results are not ordered unless you sort the returned rows or run SQL that orders them. Instead:

From getaero-io/gtm-eng-skills, MIT.

More from getaero-io/gtm-eng-skills