# ThoughtSpot objects > For the complete documentation index, see [llms.txt](https://developers.thoughtspot.com/docs/llms.txt) Source: https://developers.thoughtspot.com/docs/thoughtspot-objects # ThoughtSpot objects ThoughtSpot is a business intelligence and data analytics platform for exploring, analyzing, and sharing real-time business analytics and interactive insights. Besides being an interactive data analytics platform, ThoughtSpot provides robust, guided search functionality that business users can use to search data instantly. ThoughtSpot is different from other BI tools because ThoughtSpot Search is the core of the ThoughtSpot system. Review this page to understand how ThoughtSpot’s architecture differs from other BI tools before proceeding with the developer documentation. ## Object model hierarchy The following figure illustrates the object model hierarchy in ThoughtSpot within a single [Org]({{navprefix}}/{{orgs}}): ![Object Model Hierarchy](/docs/doc-images/images/object_model_hierarchy.png) ## Object identifiers Every object in ThoughtSpot has a globally unique ID (GUID), visible in URLs and in REST API responses as the `id` or `metadata_id` property. GUIDs are unique within a ThoughtSpot instance and thus cannot repeat in different Orgs. Objects have an additional `obj_id` property that is **user-settable** and **unique per Org**. It appears as `metadata_obj_id` in responses from the `/metadata/search` REST API. Each Org can have one object with a particular `obj_id`. The combination of `org_id` + `obj_id` is unique per instance, so it is equivalent to the object’s GUID. `obj_id` enables TML export and import across Orgs and instances, allowing ThoughtSpot to automatically determine the object’s GUID without manual GUID mapping. ### Supported object types Currently, `obj_id` is supported for the following object types: - Answers - Data Model - Logical Tables - Liveboards - Visualizations - Collections - Personalized Views ### obj\_id format and constraints `obj_id` values must meet the following requirements: | Constraint | Requirement | | --- | --- | | Allowed characters | Lowercase alphanumeric, dots, and hyphens: `[a-z0-9.-]` | | Casing | Strictly lowercase | | Maximum length | 64 characters | | GUID exclusion | Must not match a standard GUID format to prevent ambiguity | **Valid examples:** `sales.pipeline.v1`, `finance-ledger-prod`, `ingestion-worker-01` ### obj\_id resolution When an identifier is passed to a REST API endpoint that accepts an `object_identifier`, ThoughtSpot resolves it in the following order: 1. `obj_id` (user-defined identifier) 2. GUID 3. Name This resolution order enables `obj_id` to be used anywhere a GUID or name is accepted in the REST API v2.0 endpoints that support the `object_identifier` field. Backward compatibility with existing GUID-based and name-based integrations is fully maintained. > **NOTE:** obj\_id resolution is scoped to the Org. An obj\_id value is unique within a single Org. The org\_id + obj\_id combination uniquely identifies an object across the entire ThoughtSpot instance. ### Setting and updating obj\_id `obj_id` values can be set or updated using the following REST API endpoints: - `POST /api/rest/2.0/metadata/update-obj-id` Updates the `obj_id` for one or more metadata objects. Accepts the object’s GUID (`metadata_identifier`) or its current `obj_id` (`current_obj_id`). ```json { "metadata": [ { "metadata_identifier": "c1e4043a-4524-4fcb-a20f-9e7aff4dc972", "new_obj_id": "sales-pipeline-v1" } ] } ``` Or, using the current `obj_id`: ```json { "metadata": [ { "current_obj_id": "sales-pipeline-v1-c1e4043a", "new_obj_id": "sales-pipeline-v1" } ] } ``` The request accepts an array, allowing multiple objects to be updated in a single API call. > **NOTE:** Objects are assigned an automatic obj\_id after the first change to the object once the feature is enabled on your instance. The auto-generated format appends the first segment of the GUID: for example, RetailSalesRAD-KPIs-c1e4043a. If the metadata\_obj\_id property in the /metadata/search response is null, the object has not been updated since the feature was enabled. For information about using `obj_id` in CI/CD workflows, see [Deploy with TML APIs]({{navprefix}}/{{deploy-with-tml-apis}}) and [Development and deployment]({{navprefix}}/{{development-and-deployment}}). ## Data modeling A data model requires at least one [connection](https://docs.thoughtspot.com/cloud/latest/connections) and one [Table](https://docs.thoughtspot.com/cloud/latest/connect-data) to use [Search data](https://docs.thoughtspot.com/cloud/latest/search-data) to create content. Most often, there will be multiple **Tables** with a variety of [joins](https://docs.thoughtspot.com/cloud/latest/tables-join) defined in ThoughtSpot, and a [Model](https://docs.thoughtspot.com/cloud/latest/models) that brings those tables together into a presentable analytics model for end users. Data engineers with the **Can manage data** privilege can add connections either [in the UI](https://docs.thoughtspot.com/cloud/latest/connections) or via [REST API]({{navprefix}}/{{connections}}). Connections are owned and accessible only to their creator, who then imports **Tables** from the connection. Once imported, tables can be shared with other ThoughtSpot groups and users. **Tables** can have [Row Level Security (RLS)](https://docs.thoughtspot.com/cloud/latest/security-rls) rules that filter the data results based on the signed-in [username](https://docs.thoughtspot.com/cloud/latest/user-management) or the [ThoughtSpot groups](https://docs.thoughtspot.com/cloud/latest/group-management) to which the user belongs, and those rules apply to any **Model** that uses the **Table**. > **NOTE:** Worksheets are deprecated and replaced with Models in ThoughtSpot Cloud 10.12.0.cl and later versions. ### Data modeling workflow 1. Create a **connection** to a cloud data warehouse. 2. Import **tables** from the **connection**. 3. Create [**Models**](https://docs.thoughtspot.com/cloud/latest/models) (analytic data models) based on tables. 4. Create [ThoughtSpot Views](https://docs.thoughtspot.com/cloud/latest/views) or [SQL Views](https://docs.thoughtspot.com/cloud/latest/sql-views) as necessary. ThoughtSpot also supports programmatic deployment of data models via [ThoughtSpot Modeling Language (TML)](https://docs.thoughtspot.com/cloud/latest/tml) and table import from [dbt](https://docs.thoughtspot.com/cloud/latest/dbt-integration#integrate). ## Content creation ThoughtSpot Search data creates a table or chart view based on the query in the search bar and any additional view configuration applied after the search results are displayed. Search data serves the role of report builder or widget designer, while **Liveboards** serve the role of dashboards in other tools. A single search can be saved as a [**Answer**](https://docs.thoughtspot.com/cloud/latest/answers) object, or the search result can be pinned to a Liveboard. A [Liveboard](https://docs.thoughtspot.com/cloud/latest/liveboard) is a collection of visualizations in a defined layout. Visualizations are created from search data results and pinned to a Liveboard; they cannot be created directly within the Liveboard. New Liveboards can be created from the **Liveboards** page and visualizations from search data results added to them, or new Liveboards can be created when pinning an Answer retrieved from search data. ### Content creation workflow To create content: 1. Use the [Search data](https://docs.thoughtspot.com/cloud/latest/search-data) functionality to build visualizations from data sources such as **Models** or **Views**. 2. Save the search result as an **Answer** or pin it to a Liveboard as a visualization. ### Visualizations on a Liveboard Any number of visualizations from search results can be added to a Liveboard object. Pinned visualizations exist only within the Liveboard and are independent of objects saved as **Answers**. Each time a search result is pinned, a separate new visualization is created on the Liveboard. To edit a visualization on a Liveboard: 1. Go to the Liveboard. 2. Navigate to the visualization. 3. Click the **More** menu ![the more options menu](/docs/doc-images/images/icon-more-10px.png) and select **Edit**. Visualizations on a Liveboard have their own GUIDs, but the visualization objects do not exist separately from the Liveboard object. ### Tags [Tags](https://docs.thoughtspot.com/cloud/latest/tags) allow you to organize your objects and find them easily. A tag object is created by the administrator, is visible to all users, and can be assigned by any user. Tag search is always an **OR** operation: filtering on multiple tags results in all objects with any of the tags, not just those with all of the specified tags. ## Access control (sharing) ThoughtSpot’s [access control model](https://docs.thoughtspot.com/cloud/latest/data-security) works by having an `author` or `administrator` share objects with [ThoughtSpot groups](https://docs.thoughtspot.com/cloud/latest/groups-privileges) or individual users: - The creator of an object is referred to as the **author**. - The author can share the object with their groups using the **Shareable** property. - The author can share the object with other users in **Shareable** groups that the **author** belongs to, and if the other **user** is also marked **Shareable**. An administrator can share any object with any group or user without restrictions. ThoughtSpot administrators can add users locally [in the UI](https://docs.thoughtspot.com/cloud/latest/user-management) or via [REST API]({{navprefix}}/{{user-api}}). Similarly, they can manage groups and sharing privileges by using the **Groups** feature in the UI or via REST API. ### Single sign-on If [SAML]({{navprefix}}/{{configure-saml}}) or [OpenID Connect (OIDC)]({{navprefix}}/{{configure-oidc}}) integration is enabled on your instance, users who authenticate with external identity providers (IdP) can log in to ThoughtSpot with their Single Sign-On credentials. Embedded ThoughtSpot instances also support the [trusted authentication]({{navprefix}}/{{trusted-authentication}}) method to sign in application users. ## Object properties in REST API Object representations in the ThoughtSpot REST API include the following properties: - `id` GUID of the object. Unique within a given ThoughtSpot instance. - `obj_id` User-defined string identifier for the object. Unique within a given Org. - `author` GUID of the user who created / uploaded the object, or had the object transferred to them. - `owner` GUID representing the relationship between hierarchical objects. For example, a **column** would have the GUID of a **Table** or **Model** as owner. - `created` Timestamp of object creation. - `modified` Timestamp of the last time the object was modified. - `modifiedBy` GUID of the user who last modified the object. - `tags` Array of tag objects representing the tags assigned to the object. ## Object names in REST API v1 Object type names in ThoughtSpot REST API v1 differ from the current names shown in the ThoughtSpot UI. Data objects have both a `type` and a `subtypes` field in the REST API, allowing you to request all valid data objects or specify an individual subtype. The following notation is used in REST API v1 for object types: - **Answers**: `QUESTION_ANSWER_BOOK` - **Liveboards**: `PINBOARD_ANSWER_BOOK` - **Connections**: `DATA_SOURCE` - **Data objects**: `LOGICAL_TABLE`, with the following subtypes: - **Tables**: `ONE_TO_ONE_LOGICAL` - **Models**: `WORKSHEET` - **Views**: `AGGR_WORKSHEET` - **SQL views**: `SQL_VIEW` - **CSV imported data**: `USER_DEFINED` - **Joins**: `LOGICAL_RELATIONSHIP` - **Columns**: `LOGICAL_COLUMN` - **Tags**: `TAG` - **Users**: `USER` - **Groups**: `USER_GROUP` Column and join objects with their own GUIDs do exist within the ThoughtSpot system, but they are connected to **Tables**, **Models**, or other data objects. Columns and joins can be viewed or modified only within the context of the data object to which they belong. ## Related resources - [ThoughtSpot product documentation](https://docs.thoughtspot.com/home/)