Deepline Analytics

Deepline Analytics

Quick Start

bashCopy code
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.

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

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.

   bashCopy code
   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:

jsonCopy code
{
  "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:

• Pair a label dimension with its sortable date-start dimension, for example discovery_quarter_label plus discovery_quarter_start.
• Query enough groups to cover the full period range, such as rowLimit: 100 for quarters.
• Sort the returned rows by the date-start dimension; without one, parse labels like Q226 as Q2 2026.
• Ignore malformed/null buckets like Q unless the user explicitly asks about missing-date records.
• Only then present the final N rows.

Custom SQL Knobs

The semantic tool supports Aero-compatible custom SQL fields: custom_dimensions, custom_filter_expressions, steps[].source_table, steps[].ts_expr, steps[].filter_expr, steps[].events_sql. Use them when the semantic layer has the right table/metric but lacks the exact date bucket or filter the user needs. They are raw SQL snippets, so prefer named semantic dimensions and filters when they exist. Write custom dimensions expression-first with an alias, for example DATE_TRUNC('month', close_date) AS close_month, not alias-first.

Choosing Semantic Objects

• Tables describe the grain and base filters. Base filters apply automatically; mention one if it materially changes counts.
• Metric descriptions often say which time dimension they pair with. Follow the pairing: created_* instead of close_* can change the business meaning.
• Time dimensions often have both date-start and label forms. Use labels for user-facing grouped output and date-start when chronological ordering matters.
• Synonyms are hints, not payload names. Use the canonical name unless the tool explicitly supports aliases.
• Relationship-backed fields may appear as qualified names like sf_account.industry. Use them only if the YAML defines the relationship and the field.

Filters:

• Bad: { "filters": ["stage_name = 'Closed Won'"] }. SQL inside filters fails because the renderer looks for a named filter with that whole string.
• Good: { "filters": ["exclude_renewal_opportunities"] }, a named semantic filter.
• Good when no named filter exists: { "custom_filter_expressions": ["stage_name = 'Closed Won'"] }. Keep the semantic metric/table and put the raw predicate there.

Error Handling

When a semantic query fails, fix the table/metric/dimension/filter and rerun before claiming an answer. If you fall back to raw SQL, state that it is a fallback and preserve the semantic metric definition you started from.

Reporting Results

A good analytics answer includes:

• The result in plain business language.
• The semantic table, metrics, dimensions, and filters used.
• Any automatic base filters that matter, such as excluding deleted/test records.
• The time grain and whether it is created-date, close-date, occurred-date, discovery-date, or another business timestamp.
• Whether the result was limited or sampled.
• The rendered SQL when the user is debugging, validating, or likely to reuse it.
• The metric's exact term from the semantic layer: forecast, pipeline, ACV, ARR, bookings, and net revenue are not interchangeable.

Raw SQL Fallbacks

Use snowflake_run_query when the question is outside the semantic layer, when you need to debug a warehouse/schema issue, or when the semantic renderer cannot express the requested shape even with custom dimensions/filters. Start from the rendered semantic SQL whenever possible because it carries base filters, joins, and metric definitions. Do not silently replace a semantic metric with a hand-written approximation; if you change the definition, name the change and explain why.