LogoLogo
About UsCustomersResourcesGet Started for Free
  • What is Select Star?
  • 🏁Getting Started
    • 1. Data Source Setup
    • 2. Mark Service Accounts
    • 3. Hide Unwanted Datasets
    • 4. Invite Owners
    • 5. Add Documentation
    • Next Steps
  • 🔄Integrations
    • Snowflake
      • Using Key Pair Authentication
      • Using Password Authentication
      • Snowflake Tag Sync
      • Snowflake Key Pair Rotation
    • Databricks
      • Databricks on AWS
      • Databricks on Azure
    • BigQuery
    • AWS Redshift
      • Manual setup
    • Microsoft SQL Server / MS SQL (beta)
      • Query Logs
    • MySQL (beta)
      • Query Logs
    • Oracle (beta)
      • Query Logs
    • Salesforce (beta)
    • DB2 (beta)
    • PostgreSQL
      • AWS Aurora PostgreSQL
      • AWS RDS PostgreSQL
      • PostgreSQL on-prem
    • AWS Glue (beta)
    • dbt
      • dbt Cloud
      • dbt Core (open source)
      • dbt Tags
      • dbt Tests
      • dbt docs Sync
        • Github dbt docs Sync
        • Bitbucket dbt docs Sync
      • dbt Impact Report
      • dbt Project Dependencies
    • Apache Airflow (beta)
    • Tableau
      • Tableau Cloud
      • Tableau Server
    • PowerBI
    • Looker
    • Metabase
    • Fivetran (beta)
    • Mode
    • Sigma Computing
    • Sisense / Periscope (beta)
    • Looker Studio (beta)
    • ThoughtSpot
    • QuickSight (beta)
      • Event Logs
    • Hex (beta)
    • Slack
    • Monte Carlo
    • Private Network
    • Request an Integration
  • ✨Features
    • Search
    • Table Page
    • Database Page
    • Dashboard Page
    • Data Lineage
    • Entity Relationship Diagram (ERD)
    • Queries & Joins
    • Tags
    • Teams
    • Discussion
    • Downstream Notifications
    • Documentation
      • Pages
      • Metrics
        • Metrics Generation
      • Glossary
    • Automated Documentation
    • User Analytics
    • Chrome Extension
      • Organization-wide install
    • Source Tables
    • Cost Analysis
    • Schema Change Detection
    • AI Features & Settings
      • Ask AI Chatbot
    • Request a Feature
  • 🧭Data Discovery
    • Where's my data?
    • Where's my dashboard?
    • How can I get the full context of this data?
    • My dashboard looks off
    • Change management
    • I'm new to the team
    • I have a data question
  • 🗃️Data Management
    • Add Documentation
      • CSV Metadata Upload
    • Collections
    • Tags
    • Data Ownership
    • Sensitive / PII Data
    • Automated PII Detection
  • 📚Learning Data
    • Getting Started: Looker
    • Getting Started: Mode
    • Getting Started: Tableau
    • Getting Started: Snowflake
    • Getting Started: Databricks
    • Getting Started: Data Warehouse
    • Getting Started: BigQuery
      • Nested Fields
    • Getting Started: Sigma
    • Getting Started: ThoughtSpot
  • 🛠️Data Source Management
    • Manage Data Sources
    • Connect Data Source Users to Select Star
    • Custom Attributes
    • Recent Queries
  • 👥User Management
    • Invite Users
    • Roles & Permissions
    • SAML SSO
    • Importing Roles and Teams (Okta)
    • Policy Based Access Control
    • Account and User Settings
  • 💻Select Star API
    • Overview
    • API Token
    • Getting Started
    • Rich Text Descriptions via API
    • Troubleshooting
    • API Examples
    • API Reference
  • 🔓Security & Compliance
  • ❓FAQ
    • Icon Map
  • 📰Changelog
    • May 20, 2025 - Chrome Extension, Notifications, and More!
    • April 16, 2025 - Semantic Models, AI Metrics, and More!
    • March 12, 2025 - Fivetran Integration, Tableau Updates and More!
    • February 6, 2025 - Collections, Slack App Published, Salesforce Formula Lineage and more!
    • December 10, 2024 - Hex Integration, Impact Score & Snowflake Key Pair Authentication!
    • November 13, 2024 - New Navigation, Airflow and More!
    • September 30, 2024 - Upstream Data Quality Issue Tracking & 5 New Integrations!
    • August 30, 2024 - Monte Carlo, dbt Cross-Project Lineage
    • July 31, 2024 - Glossary Import, Lineage Updates & more!
    • July 9, 2024 - Lineage Explorer 2.0, Slack AI and Notifications
    • February 29, 2024 - AI Chat, Schema Change Notifications
    • February 23, 2024 - Manual Lineage Creation
    • November 23, 2023 - Bulk AI Documentation
    • October 19, 2023 - Downstream Notifications
    • October 16, 2023 - New Homepage
    • October 13, 2023 - dbt Impact Report
    • Historical Changelogs
  • Security & Compliance
  • System Status
Powered by GitBook
On this page
  • Introduction
  • Rich Text Descriptions via API Using SlateJS
  • Rich Text Descriptions via API Using Markdown
  • Conclusion

Was this helpful?

  1. Select Star API

Rich Text Descriptions via API

PreviousGetting StartedNextTroubleshooting

Last updated 1 year ago

Was this helpful?

Introduction

Select Star uses rich text descriptions in various parts of the platform, and one of the primary areas where rich text descriptions are used is in the documentation, metrics, and descriptions of metadata objects. These descriptions provide users with a clear and concise explanation of what each object represents and how it can be used. Additionally, rich text descriptions are used to provide context and additional information for tags. This helps users understand how tags are used and what they represent.

Select Star supports both SlateJS and Markdown for formatting text in rich text descriptions. SlateJS library provides a simple and flexible way to create and edit rich text content and provides a wider range of formatting options, including mentions. Whereas with Markdown, it wasn’t possible to create mentions.

Users can now choose the format that best suits their needs when creating and updating rich text descriptions in Select Star. If users have pre-existing documentation expressed in Markdown, syncing it with the Select Star platform will be seamless.

This document will cover how to update rich text descriptions via API using SlateJS and Markdown formats.

Rich Text Descriptions via API Using SlateJS

What is SlateJS?

SlateJS is a JavaScript library that allows you to create and edit rich text content in a web application. It is built on top of React and leverages its component-based architecture. SlateJS provides a rich set of features for formatting text, including headings, lists, tables, links, and media embeds. Additionally, SlateJS allows developers to extend its functionality by creating custom plugins.

SlateJS uses an immutable data structure called a Slate document to represent the rich text content. This document is composed of nodes, which can either be text or other types of content, and marks, which represent the formatting applied to the text.

For more information on SlateJS go to documentation

Supported SlateJS Features

Select Star supports the following SlateJS features for formatting text in rich text descriptions:

text, paragraph, h1, h2, h3, h4, h5, h6, blockquote, ul, ol, code, codeblock, span, link, table, thead, tbody, tr, td, th, and mentions.

These features provide a wide range of options for creating and formatting content, from simple paragraphs to complex tables and mentions of other objects in Select Star. With these features, users can create rich, informative descriptions for documentation, metrics, and metadata objects. Additionally, the ability to use mentions helps users collaborate and communicate effectively within the platform.

Example

To update the rich text description field via API using SlateJS format, you need to send a PATCH request to the API endpoint with the updated content in SlateJS format. Here is an example of a Python script making a request to update a rich text description:

import json
import requests

api_key = "INSERT_API_KEY"
base_url = "https://api.production.selectstar.com/v1"
guid = "INSERT_METADATA_OBJECT_GUID"

data = {
    "richtext_description": json.dumps([
        {"type": "h1", "children": [{"text": "Description"}]},
        {"type": "paragraph", "children": [{"text": "This is SlateJS description", "bold": True}]}
    ])
}
requests.patch(f"{base_url}/metadata/{guid}/", data, headers={"Authorization": f"Token {api_key}"})

After making this request, you’ll be able to see this in the Select Star platform as a result:

In this example, we are updating the rich text description with a given GUID with a new H1 header and a paragraph containing the text "This is SlateJS description" in bolded letters. The content is represented in SlateJS format as a JSON object.

Mentions example

Mentions must be placed inside a parent paragraph component. They'll also show in mentioned object's "Mentioned by" section. To mention an object, you need to put its GUID and name into a mention component.

import json
import requests

api_key = "INSERT_API_KEY"
base_url = "https://api.production.selectstar.com/v1"
guid = ""  # GUID of the object whose description is being updated
mentioned_guid = ""  # GUID of the object that is mentioned
mentioned_name = ""  # Name of the object that is being mentioned

data = {
    "richtext_description": json.dumps([
        [{"type":"paragraph","children":[{"children":[{"text":""}],"mention":{"guid":mentioned_guid,"name":mentioned_name},"type":"mention"}]}]
    ])
}
requests.patch(f"{base_url}/metadata/{guid}/", data, headers={"Authorization": f"Token {api_key}"})

Ensure the GUID is valid and its associated object exists; otherwise, the mention will be marked as invalid. The "name" field in rich text is used exclusively for plain text relevant to search. In the UI, we'll display the name by pulling the latest data for each mention using its GUID. After this request, you'll see the result on the Select Star platform:

Rich Text Descriptions via API Using Markdown

What is Markdown?

Markdown is a lightweight markup language that allows you to create formatted text using plain text syntax. It is commonly used for writing documentation and README files. Markdown provides a simple way to format text, including headings, lists, links, and emphasis. Additionally, Markdown allows developers to extend its functionality by creating custom extensions.

Supported Markdown Features

Select Star supports the following Markdown features for formatting text in rich text descriptions:

text, paragraph, headings (h1 to h6), blockquote, ul, ol, codeblock, link.

These features provide a wide range of options for creating and formatting content, from simple paragraphs to complex lists and codeblocks. With these features, users can create rich, informative descriptions for documentation, metrics, and metadata objects.

Example

To update the rich text description field via API using Markdown format, you need to send a PATCH request to the API endpoint with the updated content in Markdown format. Here is an example of a Python script making a request to update a rich text description:

import json
import requests

api_key = "INSERT_API_KEY"
base_url = "https://api.production.selectstar.com/v1"
guid = "INSERT_METADATA_OBJECT_GUID"

data = {
    "richtext_description": "## Description\n\n**This is a Markdown description**"
}
requests.patch(f"{base_url}/metadata/{guid}/", data, headers={"Authorization": f"Token {api_key}"})

After making this request, you’ll be able to see this in the Select Star platform as a result:

In this example, we are updating the rich text description with a given GUID with a new H2 header and a paragraph containing the text "This is a Markdown description" in bolded letters. The content is represented in Markdown format as a string.

Conclusion

In conclusion, Select Star offers two options for formatting text in rich text descriptions: SlateJS and Markdown.

SlateJS provides a wider range of formatting options, including mentions. Users can choose the format that best suits their needs when creating and updating rich text descriptions in Select Star.

SlateJS is a powerful JavaScript library that provides a flexible and easy-to-use way to create and edit rich text content in web applications. However, it is essential to ensure that the new content is in the correct format to avoid rendering failures.

Markdown is a lightweight markup language that provides a simple and intuitive way to format text using plain text syntax. It is easy to learn and use, making it an excellent choice for creating documentation.

Updating rich text descriptions via API using either format requires a PATCH request with the updated content in the appropriate format.

💻
https://docs.slatejs.org/
MENTIONED_BY_OBJECT_NAME is linked to MENTION_NAME