Blocks

A block is a named, reusable query saved as a .dql file. It carries the SQL (or a semantic metric query) plus an owner, a domain, a description, tests and a chart. Ask answers from certified blocks first, and App tiles are built from blocks.

Where blocks come from

Start from	How
Existing SQL files or pasted SQL	Import SQL
A notebook cell	Save Block on the cell. See Notebooks.
An Ask answer you want to keep	Save as block on the answer, or the review draft Ask saves for you. See Answers that need review.
Nothing yet	New block in Block Studio
A terminal	zlens new block "<name>" or zlens import sql <path>

Whichever way you start, the result is a draft. A person certifies it later. See Save and certify.

Find your blocks

1. In the left rail, click Blocks.
2. The sidebar lists blocks in folders by domain. Draft blocks that Ask or Import SQL saved for review are in a Drafts folder.
3. Narrow the list with Search blocks… or the domain menu (All domains).

The line under the search box counts them, for example 3 blocks · 1 draft · all domains.

Each row shows the block's name, domain and status. A Private badge means the block is saved only on your machine, outside git, until you publish it.

Block status

Block Studio shows a block's status as a badge:

Badge	Means
Draft	Saved, not reviewed. Ask does not use it as a trusted answer.
Certified	A person certified it. Ask and Apps treat it as trusted.
In review	Marked for review.
Recertify	Something it depends on changed; certify it again.
Deprecated	Retired. If it names a replacement, Block Studio shows Replaced by and links to it.

What a block file looks like

// dql-format: 1

block "Top customers by lifetime spend" {
  status = "certified"
  domain = "uncategorized"
  type = "custom"
  description = "The ten customers with the highest lifetime spend, with their order counts."
  owner = "analytics@example.com"
  query = """
    select customer_name, count_lifetime_orders, lifetime_spend
    from dev.customers
    order by lifetime_spend desc
    limit 10
  """
  visualization {
    chart = "table"
  }
}

• Blocks are saved under blocks/<domain>/, or domains/<domain>/blocks/ when your project uses domain folders.
• Drafts that Ask or Import SQL created go in a _drafts/ folder until they are certified.
• Each block has a companion file under semantic-layer/blocks/ that records its review status and, once certified, who certified it.

The full syntax is in the DQL language reference.