--- title: "Objects" slug: "product-manual-compass-objects" updated: 2026-10-29T17:58:09Z published: 2026-10-29T17:58:09Z canonical: "docs.ursahealth.com/product-manual-compass-objects" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.ursahealth.com/llms.txt > Use this file to discover all available pages before exploring further. # Objects A Compass Object is a table or view the AI builds in the client database, documented with a name, a description, and per-column metadata. Unlike a [finding](/v1/docs/product-manual-compass-findings), which captures one query result, an object is durable data that other analyses and [apps](/v1/docs/product-manual-compass-apps) can read. ## Creating an Object **New Object** on the Objects screen asks for a name, a table name, an optional description, and tags, and then opens the object's build workspace. You describe the object you want in a conversation, and the AI builds it. The object is built under its table name in two schemas: the **compass** schema holds the draft, and the ursa schema holds the published version (see [Publishing](/docs/product-manual-compass-objects#publishing)). Creating an object is refused if either schema already has something by that name. The name, description, and tags are yours to write and can be changed later. The AI reads the description but does not write it. ## The Build Workspace The AI investigates with QUERY_DATABASE, GET_OBJECT_METADATA, and GET_MEASURE_METADATA, and builds the object with SET_COMPASS_OBJECT. It supplies only the select, along with whether the object is a table or a view, its primary key, and any column labels and descriptions. The table name is set by you, not the AI, so the AI cannot build anything else. Each SET_COMPASS_OBJECT replaces the draft. The new version is built and checked alongside the old one first, so a query that fails, or a key that does not hold, leaves the previous version in place. The panel beside the conversation shows the draft's columns and can preview its rows. ### Compacting the Conversation **Compact Conversation** on the object's page replaces most of the build conversation with a summary. The AI keeps its setup instructions, your starting request, and the object's current SQL and column metadata. The replaced messages can still be viewed on the build screen with **Show earlier messages**. Compacting cannot be undone. ## Column Metadata The recorded column metadata comes from the database, not the AI. Once the object is built, its real columns and data types are read back by introspection, and the AI's field descriptions are laid on top of that, so field descriptions can be sparse. A column the AI does not mention keeps the label and description it already had when the object is rebuilt. ## The Primary Key Every object declares a primary key: the columns that together identify one row. It is how the object states its grain — one row per patient, or per patient per month, or per claim line — which is the first thing anyone needs to know before joining to it and the one thing column descriptions alone never make clear. ## Measure-like Objects An object can declare that it is a measure: a denominator of observations, each with a numerator. Apps then read it the way they read a [measure](/v1/docs/product-manual-compass-apps), so rates come out right however the app groups the rows. Most objects are not measures, and the AI declares a type only when the object is one. - **Normal-form event**: one row per observation, keyed on the columns that identify it, with a denominator `d` and a numerator `n`. - **Long-form event**: an observation together with any number of numerator records, one row per record, such as a patient with each of their claims. The observation's columns repeat on each of its records. The primary key is the observation's columns followed by `rank_within_observation`, and the AI marks which columns describe the numerator record, which the object's page shows in a **Numerator** column. An app can then split the numerator by those columns while still measuring each part against the whole denominator. The build checks the object against its type and refuses one that does not conform. For example, a long-form object fails if an observation's own columns differ from one record to the next, or if its `n` is not the total of its records' `n_component`. Like a failed key, a refused build leaves the previous version in place. The same check runs again whenever the object is rebuilt, published, or refreshed by ELT. Because of that, the type and the numerator columns are set only by building the object and cannot be changed from **Edit**. ## Publishing The draft in the compass schema changes every time the AI rebuilds it. Publishing builds the current draft into the ursa schema, where it stays as it is until the next publish. That gives anything built on the object a stable version to rely on while work continues on the draft. An object cannot be published if it relies on unpublished objects. Those upstream objects must be published first and the references updated before publishing is allowed on the downstream object. Only **bespoke authors** can publish. The published object is built by the main database user, which can write outside the compass schema; the AI cannot publish, and neither can other Compass Authors. Each publish freezes that revision. Editing the object afterwards — through the AI or by changing column labels — starts a new draft, and the object's page shows a banner with both revision numbers and a **Show Published** toggle. [Apps](/v1/docs/product-manual-compass-apps) can be built on either version: `compass.<table name>` reads the draft, and `ursa.<table name>` reads the published version. An app can only be published once every Compass Object it reads is a published `ursa.` one. ## Objects List and Detail **Objects** in the sidebar lists every object with its table name, type, publishing status, owner, when it was created, and when its data was last built, searchable by name, description, table name, or owner. **Data As Of** is when a table's data was last built. Views have no Data As Of, because a view holds no data of its own. **Edit** on the detail page opens the name, the table name, the description, the tags, and each column's label and description for editing. The SQL, the object type, the primary key, the measure type and numerator columns, and each column's name and data type are set by building the object and cannot be changed from here. Changing the table name moves the draft and, if there is one, the published version to the new name. Renaming a published object takes a bespoke author. Apps and other objects that read the old name are not updated and stop working until they are pointed at the new one. An object's documentation is also available to the AI in any session: GET_OBJECT_METADATA for `compass.<table name>` returns the draft, and for `ursa.<table name>` the published version. ## Rebuilding an Object A table's data is a snapshot of what the query returned when it was built. **Rebuild** re-runs the draft's query and replaces the draft table's contents. For a published object, bespoke authors see **Refresh Published** instead, which does the same for the published version without changing its definition. The columns are whatever the query returns now. Columns that survive keep their labels and descriptions, a column that has appeared gets a humanized label, and one that has gone away takes its documentation with it. A rebuild runs over the page's live connection, so progress is shown as it goes and there is no time limit on it. ## Deleting an Object **Delete** on the detail page drops the draft and, if there is one, the published version from the database, and removes the object from the list. This cannot be undone. If a drop fails, nothing is removed and the database's error is shown. ## Access Control - **Compass Authors** (and above) can create, build, preview, edit, rebuild, compact, and delete objects that have not been published. - **Bespoke authors** can also publish, refresh the published version, and rename or delete a published object. - **Reviewers** do not have access to objects. - There is no sharing: every Compass Author sees every object, regardless of who created it.