Skip to main content

Key Concepts and Terminology

This page defines the core objects in Crow's Nest and how they relate to each other. Understanding these terms will help you navigate the rest of the documentation.

Core objects​

Data Source Config​

A data source config is a connection to an external system — a Tulip instance, a SQL database server, or an MQTT broker. Admins create and manage these in Organization Settings. Each config stores the credentials and connection details needed to reach that system.

Think of a data source config as "which database server to talk to." A data connection (below) is "which specific table or query to run on that server."

Data Connection​

A data connection (also called a "table connection") defines a specific query or data feed from a data source. There are four kinds:

  • Tulip — A specific table from a Tulip instance, with optional field selection, filters, and caching.
  • SQL — A SQL query (SELECT statement) run against a PostgreSQL or MSSQL database.
  • MQTT — A subscription to a topic on an MQTT broker, delivering real-time messages.
  • Static — Rows of data entered directly or uploaded from a CSV file.

Widgets use data connections to fetch the data they display. One data connection can be shared across multiple widgets.

Widget​

A widget is a self-contained visual component built with HTML, JavaScript, and CSS. Widgets fetch data from one or more data connections using the getData() function, then render that data however you choose — tables, charts, status indicators, or anything else you can build in a browser.

Widgets can also define inputs (text fields, numbers, dropdowns, dates) that let dashboards pass values into them. This makes a single widget reusable across different contexts.

See Widgets Overview for more.

Dashboard​

A dashboard is a grid-based layout of widgets. You drag and drop widgets onto a 24-column grid, resize them, and optionally configure dashboard-level inputs that control what data each widget displays.

Dashboards can be starred as favorites and scheduled to send email snapshots on a recurring basis.

See Dashboards Overview for more.

How the objects relate​

Data Source Config (admin-managed)
  └── Data Connection (user-created)
        └── Widget (uses one or more connections)
              └── Dashboard (arranges one or more widgets)
  • A data source config can have many data connections pointing to it.
  • A widget can use one or more data connections.
  • A dashboard contains one or more widgets arranged in a grid.
  • Each widget can appear on one dashboard at a time.

User roles​

Crow's Nest has three roles within an organization:

RoleWhat they can do
AdminFull access. Manage data source configs, users, roles, and organization settings. Create and edit all widgets, connections, and dashboards.
MemberCreate and edit their own widgets, connections, and dashboards. Can only access data source configs that an admin has granted them.
View-OnlyView dashboards and widgets. Cannot create, edit, or delete anything.

Admins assign roles when inviting users. See Managing Users and Roles for details.

Other terms​

  • Observatory — The home page. Shows a visual map of all data connections, widgets, and dashboards in your organization.
  • AI Agent — A built-in assistant in the widget editor that helps generate and refine widget code.
  • Cartography — An AI-powered tool that discovers relationships between your data connections.
  • Snapshot — A rendered PDF of a dashboard, sent by email on a schedule.