ThoughtSpot objects
Table of Contents
ThoughtSpot is a business intelligence (BI) and data analytics platform for exploring, analyzing, and sharing real-time business analytics and interactive insights. ThoughtSpot Search is the core of the ThoughtSpot system, making it distinct from other BI tools.
This page explains how ThoughtSpot’s architecture differs from other BI tools. Read this before proceeding with the developer documentation.
Object model hierarchy🔗
The following figure illustrates the object model hierarchy in ThoughtSpot within a single Org:
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. Because GUIDs are generated separately on each instance, a copy of an object in another Org or instance has a different GUID.
Supported objects also have an Object ID (obj_id) property that is user-settable and unique per Org. The combination of org_id + obj_id is unique per instance, so it is equivalent to the object’s GUID. The obj_id appears as metadata_obj_id in responses from the /metadata/search REST API.
Because you choose the obj_id, related copies of an object in different Orgs and instances can share the same value. This allows ThoughtSpot to match objects during TML import without manual GUID mapping, and allows you to reference objects in REST API requests and ThoughtSpot URLs with the same identifier in every environment.
For more information, see the following pages:
-
Object ID (obj_id)
Supported object types,obj_idformat and constraints, how identifiers are resolved, and how to set or update anobj_id. -
Object ID in ThoughtSpot URLs
Use anobj_idinstead of a GUID in Liveboard, Answer, Collection, data object, and connection URLs.
Data modeling🔗
A data model requires at least one connection and one Table to use Search data to create content. In most cases, there are multiple Tables with a variety of joins defined in ThoughtSpot, and a Model 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 or via REST API. 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) rules that filter the data results based on the signed-in username or the ThoughtSpot groups 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🔗
-
Create a connection to a cloud data warehouse.
-
Import tables from the connection.
-
Create Models (analytic data models) based on tables.
-
Create ThoughtSpot Views or SQL Views as necessary.
ThoughtSpot also supports programmatic deployment of data models via ThoughtSpot Modeling Language (TML) and table import from dbt.
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 object, or the search result can be pinned to a Liveboard.
A 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:
-
Use the Search data functionality to build visualizations from data sources such as Models or Views.
-
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:
-
Go to the Liveboard.
-
Navigate to the visualization.
-
Click the More menu
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 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 works by having an author or administrator share objects with ThoughtSpot groups 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 or via REST API v2.0. Similarly, they can manage groups and sharing privileges by using the Groups feature in the UI or via REST API v2.0.
Single sign-on🔗
If SAML or OpenID Connect (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 method to sign in application users.
Object properties in REST API🔗
The POST /api/rest/2.0/metadata/search REST API v2.0 endpoint returns the following properties for each object:
-
metadata_id
GUID of the object. Unique within a given ThoughtSpot instance. -
metadata_obj_id
User-defined string identifier for the object (obj_id). Unique within a given Org. For more information, see Object ID (obj_id). -
metadata_name
Name of the object. -
metadata_type
Object type, for example,LIVEBOARD. For the list of types, see Object types in REST API v2.0.
The metadata_header object in the response includes the following properties:
-
id
GUID of the object. Same asmetadata_id. -
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.
For more information, see Metadata search API.
Object types in REST API v2.0🔗
Object type names in ThoughtSpot REST API v2.0 differ from the names shown in the ThoughtSpot UI. Use the following values in the type attribute of REST API v2.0 requests, such as /metadata/search:
-
Liveboards:
LIVEBOARD -
Answers:
ANSWER -
Connections:
CONNECTION -
Data objects:
LOGICAL_TABLE -
Joins:
LOGICAL_RELATIONSHIP -
Columns:
LOGICAL_COLUMN -
Tags:
TAG -
Users:
USER -
Groups:
USER_GROUP -
Collections:
COLLECTION
For the LOGICAL_TABLE type, you can also specify the following values in the subtypes attribute to filter the results:
-
Tables:
ONE_TO_ONE_LOGICAL -
Models:
WORKSHEET -
Private Models:
PRIVATE_WORKSHEET -
Views:
AGGR_WORKSHEET -
SQL Views:
SQL_VIEW -
CSV imported data:
USER_DEFINED
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.