Surfaces Guide

Goal: Understand surfaces and connect your data to them.

---

What is a Surface?

Concept	Explanation
Execution boundary	Where code and queries actually run
Domain container	Group related queries together
Data scope	Defines what data is available to queries

---

Surface vs Workspace

Level	Purpose	Contains
Workspace	Management, holistic view	Connections, surfaces, team
Surface	Execution, specific goals	Warm queries, APIs

---

Prerequisites

Before creating a surface:

• At least one data connection with data flowing
• Workspace canvas open

---

Creating a Surface

Option A: Drag and Drop

1. Locate Surface in the Node Bank (left edge, cyan layered squares icon)
2. Drag the Surface onto the canvas
3. Click the Surface node to open Inspector
4. In Settings, name it descriptively (e.g., "production-monitoring")
5. Commit your changes (click save icon, top-left)

Option B: Ask Azi

---

Connecting Data to Surfaces

Data must "spill onto" the surface before you can query it.

1. Hover over your data connection node
2. Click the connection handle (small circle)
3. Drag line to the surface
4. Release to connect
5. The edge will display a "feeds" label showing the data relationship

Verifying the Connection

After connecting:

1. Click the surface node
2. Open Inspector
3. Check Connected Sources section
4. Your data connection should be listed

Multiple Connections

A surface can receive data from multiple connections:

Setup	Result
Connection A → Surface	Data A available
Connection A + B → Surface	Data A + B available
Connection A + B + C → Surface	Data A + B + C available

Queries inside the surface can access all connected data.

---

Inside a Surface

To enter a surface:

1. Click the surface node to open its Inspector
2. Click the Manage Surface icon (cyan layered squares) in the Inspector
3. You're now "inside" the surface
4. The canvas shows surface-level view

Inside, you'll find:

• Node Bank - Drag Warm Query nodes onto the surface canvas
• Connected data - See which connections are attached (with "feeds" edges)
• Surface settings - Configure in the Inspector panel

---

Surface Settings

In the surface Inspector:

Setting	Purpose
Name	Display name in UI
Description	Documentation for team

---

Surface Organization Patterns

Pattern	When to Use
One per domain	Separate surfaces for production, quality, maintenance
One per team	Each team owns their surfaces
One per use case	Dashboards, alerts, reports each get a surface

---

Commit Your Changes

1. Click the Save icon (top-left) - it glows purple when there are uncommitted changes
2. After committing, click Deploy to make changes live
3. The green checkmark confirms your workspace is deployed

---

Next Steps

If you want to...	Go to...
Build queries in surfaces	Warm Queries Guide →
Understand commit workflow	Save vs Commit →