{
"record_offset" : 0,
"record_size": 10,
}Search metadata
Table of Contents
The /metadata/search endpoint is the most versatile of all metadata endpoints. It can be used to search for lists or to retrieve very detailed information about specific objects. This endpoint replaces metadata/list, metadata/listobjectheaders, metadata/details, and metadata/listvizheaders from REST API v1.
The overall structure of metadata/search request is described as a combination of objects.
Note that many parameters in the request are optional, and leaving the parameter name out entirely has a different effect from including the parameter and specific values.
Throughout this article, requests and responses will be shown as JSON, without any of the code to send the requests. The V2.0 Playground generates requests that always include the default values for any parameters that have them, but this article excludes them. Assume every request you see has the following parameters in addition to what is shown:
If you are not using filtering options such as tag_identifiers, type, created_by_user_identifiers, modified_by_user_identifiers, owned_by_user_identifiers, exclude_objects, include_auto_created_objects, or favorite_object_options, set record_size to -1 and record_offset to 0 for precise results.
Response format🔗
The response from any call to metadata/search will resemble the following:
[
{
"metadata_id": "4081f38c-1f26-4354-a418-af14136e3bd7",
"metadata_name": "Snowflake",
"metadata_type": "LIVEBOARD",
"dependent_objects": null,
"incomplete_objects": null,
"metadata_detail": null,
"metadata_header": {...},
"visualization_headers": null,
"stats": null,
},
...
]The value of metadata_header is a complex object with the most important set of attributes of the item. Note that author is the creator or current user who has been assigned the ownership of the object, while owner describes a hierarchical relationship between ThoughtSpot objects (for example, this Liveboard has an owner property identical to its own id property):
"metadata_header": {
"hasTabs": false,
"modelVersion": "V1",
"hasMandatoryFilter": false,
"isMandatoryFilterValueSelected": true,
"totalContainerCount": 36,
"id": "2681a4d3-98ad-4d37-b5c0-378dbac36320",
"indexVersion": 14,
"generationNum": 48857,
"name": "Snowflake",
"description": "Connection to Snowflake data warehouse",
"author": "67e15c06-d153-4924-a4cd-ff615393b60f",
"authorName": "UserA,
"hasLenientDiscoverability": false,
"descriptionAutoGenerated": false,
"authorDisplayName": "UserA",
"created": 1592450556601,
"modified": 1592605750424,
"modifiedBy": "67e15c06-d153-4924-a4cd-ff615393b60f",
"owner": "2681a4d3-98ad-4d37-b5c0-378dbac36320",
"isDeleted": false,
"isHidden": false,
"isAutoCreated": false,
"isAutoDelete": false,
"resolvedObjects": {},
"tags": [],
"aiAnswerGenerationDisabled": false,
"isExternal": false,
"isDeprecated": false,
"isSharedViaConnection": false
}You’ll notice a number of other keys with a null value. Various request parameters cause those sections of the response to be filled in with additional details.
Lists of metadata🔗
The /metadata/search API performs listing functions when you do not send specific object IDs as part of your request.
The basic metadata selectors are placed in the metadata parameter as an array of Metadata List objects.
For example, to get all Liveboards, you need to send only a single metadata object with type parameter set to LIVEBOARD.
{
"metadata": [
{
"type": "LIVEBOARD"
}
]
{|
Note
|
The |
To match names against a pattern, you can use the name_pattern parameter, including % for wildcard purposes:
{
"metadata": [
{
"type": "LIVEBOARD",
"name_pattern": "Standard %"
}
]
}You may still want to process the result set further within your programming language.
Retrieve specific objects🔗
The identifier parameter allows referencing an object by name or by object GUID.
Specific objects can be retrieved via the object GUID without specifying type:
{
"metadata": [
{
"identifier": "009d8d6c-5026-47a9-96d7-9e0f84896d17"
}
]
}You can specify an object name in the identifier key, but you must include the type in this request:
{
"metadata": [
{
"type": "LIVEBOARD",
"identifier": "My Great Liveboard"
}
]
}The response to a metadata/search request takes the form of an array of Metadata Response Objects:
"[
{
"metadata_id": "009d8d6c-5026-47a9-96d7-9e0f84896d17"
"metadata_name": "New Liveboard"
"metadata_type": "LIVEBOARD"
"dependent_objects": null
"incomplete_objects": null
"metadata_detail": null
"metadata_header": {...}
"visualization_headers": null
"stats": null
},
...
]The metadata_header key is always returned with values, regardless of the request. This section resembles the V1 REST API response from the metadata/list and metadata/listobjectheaders endpoints.
Filtering and sorting🔗
sort_options🔗
The sort_options parameter requires Metadata Search Sort Options to sort on one field of the metadata response either in the ascending (ASC) or descending (DESC) order:
{
"metadata": [
{
"type": "LIVEBOARD"
}
],
"include_visualization_headers": true,
"sort_options" : {
"field_name": "LAST_ACCESSED",
"order": "ASC"
}
}If you need multiple levels of sorting, you’ll have to parse the response programmatically and apply a sorting algorithm on the properties within each response item.
permissions🔗
You can filter responses based on who can access the object, that is, who the content has been shared to, using the permissions parameter.
While the permissions parameter filters the response set of metadata/search, the objects in the response do not list the full set of assigned permissions. Please use the /security/metadata/fetch-permissions/` endpoint for a full listing, which replaces the individual security endpoints in the v1 REST API, such as the get object permission details for a specific object type endpoint.
The permissions object takes an array of objects that define a principal and a share_mode. principal is an object with a type of USER or USER_GROUP and an identifier, either the name or the GUID of the principal:
{
"metadata": [
{
"type": "LIVEBOARD"
}
],
"permissions" : [
{
"principal": {
"type": "USER_GROUP",
"identifier": "Administrators"
},
"share_mode": "MODIFY"
}
]
}The share_mode can be READ_ONLY ('Can View' in the UI), MODIFY ('Can Edit' in the UI), or NO_ACCESS, which shows denial of access and is not visible in the UI.
tag_identifiers🔗
Thoughtspot objects can be assigned multiple tags, and the /metadata/search endpoint allows you to filter for items with a set of tags using the tag_identifiers parameter, which takes an array of tag names or GUIDs.
Including multiple tags behaves as a logical OR operation, retrieving all content with any of the listed tags. The following request body retrieves any content tagged with Staging or Accounting tags:
{
"metadata": [
{
"type": "LIVEBOARD"
}
],
"tag_identifiers": [
'Staging',
'Accounting'
]
}created_by_user_identifiers and modified_by_user_identifiers🔗
The created_by_user_identifiers and modified_by_user_identifiers parameters take a list of user names or GUIDs, and filter the results to only those with objects that were created by or modified by those users.
{
"metadata": [
{
"type": "LIVEBOARD"
}
],
"created_by_user_identifiers": [
'bryant.howell',
'bill.back'
]
}favorite_object_options🔗
The favorite_object_options parameter takes an object that filters the result list to only objects that are added as favorites.
To retrieve the favorites list for the user making the request, set the include property to true:
{
"metadata": [
{
"type": "LIVEBOARD"
}
],
"favorite_object_options": {
"include": true
}
}A user with administrator privileges can request on behalf of other users by specifying the user name or GUID in the user_identifiers array. If you send multiple user identifiers, the result includes a full set of all objects set as favorites for all listed users, with no particular way to identify who favorited which content.
{
"metadata": [
{
"type": "LIVEBOARD"
}
],
"favorite_object_options": {
"include": true,
"user_identifiers": ['bill.back']
}
}exclude_objects🔗
The exclude_objects parameter takes an array of objects that can exclude items from the returned list:
{
"metadata": [
{
"type": "LOGICAL_TABLE"
}
],
"exclude_objects": [
{
"identifier": "Retail Sales",
"type": "LOGICAL_TABLE"
}
]
}Additional response details🔗
There are a number of parameters that add new data to the response, allowing the metadata/search endpoint to answer questions that require multiple API calls in the v1 REST API.
include_visualization_headers🔗
The v1 REST API endpoint metadata/listvizheaders retrieves the header details of all individual visualizations on a Liveboard.
In v2, the include_visualization_headers parameter adds the visualization headers to the response.
{
"metadata": [
{
"identifier": "009d8d6c-5026-47a9-96d7-9e0f84896d17"
}
],
"include_visualization_headers": true
}Note from above that the response to every request has the visualization_headers key, but the value will be null unless include_visualization_headers is true, and the object type is LIVEBOARD.
The include_visualization_headers adds the array of visualization headers for every element in the response, so you can request a list of all Liveboards and all the visualizations on those Liveboards all at once.
include_details🔗
The v1 REST API has an endpoint called metadata/details for retrieving a very large and complex object containing as much detail as possible about the requested object and its relationships with other objects within ThoughtSpot.
The include_details parameter in the metadata/search API request adds the equivalent details object to each element retrieved by metadata/search to the response under the metadata_detail key.
{
"metadata": [
{
"identifier": "009d8d6c-5026-47a9-96d7-9e0f84896d17"
}
],
"include_details": true
}The details of each object type is a complex object that is unique to each object type within ThoughtSpot.
include_dependent_objects🔗
Data objects in Thoughtspot like Tables and Worksheets have dependent objects that connect to them. Liveboards and Answers do not have dependent objects, they can only be a dependent object.
An object can only be deleted if all of its dependent objects are deleted first.
The v1 REST API had an entire set of dependent objects APIs for retrieving these relationships.
The equivalent information is retrieved from metadata/search by setting the include_dependent_objects parameter to true:
{
"metadata": [
{
"identifier": "782b50d1-fe89-4fee-812f-b5f9eb0a552d"
}
],
"include_dependent_objects": true
}The response will now have an object for the dependent_objects key. This object is of a complex format, that always starts with a key that is the metadata object’s own GUID, with the value being an object with keys of the various internal object type identifiers (note "LOGICAL_TABLE" and "QUESTION_ANSWER_BOOK" in the response below):
"dependent_objects":{
"782b50d1-fe89-4fee-812f-b5f9eb0a552d":{
"LOGICAL_TABLE": [...]
"QUESTION_ANSWER_BOOK": [...]
}
}The array for each object type will contain the metadata headers for the various dependent objects, including the GUIDs necessary to do any further actions on those dependent objects as the id property.
Common use cases for the dependent objects include tagging, auditing proper sharing, proper deletion, and any other tasks for applying a change in bulk to related objects in one data model.
include_stats🔗
The include_stats boolean option causes the stats key of the response to be filled with an object with statistics about user access to the object.
include_worksheet_search_assist_data🔗
The include_worksheet_search_assist_data boolean parameter includes details about the Search Assist feature within the response.
include_hidden_objects, include_incomplete_objects, include_auto_created_objects🔗
The metadata/search response typically excludes objects that are auto-created, hidden, or incomplete, as these objects represent internal use cases typically not seen or modified by any end user.
The include_hidden_objects, include_incomplete_objects, and include_auto_created_objects boolean parameters can be used if you have a known use-case where you need metadata information from an object marked under one of these categories (for example, the internal hidden answer objects that represent each visualization on a Liveboard).