Getting Started

Getting Started Guide

In this quick start guide, you'll learn how to:
  • fetch a list of table objects with their guids
  • read a table's metadata
  • write a description to that table's metadata
In order to start using the API, you'll have to already have signed up your organization and performed metadata/catalog ingestion.
For reference, base url for all api calls is https://api.production.selectstar.com/v1/. And note that all of the API urls have a trailing backslash.

Client

Any http client can be used to make calls to the API. For usage in a script, you may choose a library like requests for Python or axios for Node. For one-off testing, you might use something like postman.
For the purpose of these examples, this guide uses curl on the command line, and the calls should be straightforward to translate to other clients.

Authentication

First, go to the API Token page to find out how to generate an API token. When you're done with that, proceed to the next steps.
Once you have your token, you'll need to include it in any calls you make to the API. Set the Authorization header for bearer authentication like so:
1
Authorization: Token <token>
Copied!
In curl you can set the header using the -H flag:
1
curl https://api.production.selectstar.com/v1/tables/ -H "Authorization: Token <your_token>"
Copied!
With authorization set, you can proceed to making a call to the API endpoint.

Making the Call

Read a List of Tables

The end goal of this quick start is to be able to write a new description to a table. But in order to update a table, Select Star needs to know the table's guid; how can this be identified?
The endpoint you'll need to query is:
1
GET /tables/
Copied!
There's many query parameters which allow filtering the result, such as search_name or serach_description. For this example, let's search for names which include the substring sales.
1
curl -H "Authorization: Token <your_token>" "https://api.production.selectstar.com/v1/tables/?search_name=sales"
Copied!
(Note that curl issues a GET request by default, even though you don't see it in the command)
The response body will looks something like: (... indicates details on the object omitted here)
1
{
2
​
3
"count": 1,
4
"schema_count": 1,
5
"next": "http://url-to-next-page.selectstar.com",
6
"previous": "http://url-to-previous-page.selectstar.com",
7
"results": [
8
{
9
"guid": "ta_UUyFgbgRhVqhhHa5WCjBaa",
10
"database": {...},
11
"schema": {...},
12
"name": "sales",
13
"search_name": "dwh.analytics.sales",
14
"description": "global sales",
15
"created_by": {...},
16
"dsuser_created_by": {...},
17
"business_owner": {...},
18
"technical_owner": {...},
19
"updated_on": "2021-08-23T23:35:51Z",
20
"last_updated_on": "2021-08-23T23:35:51Z",
21
"last_queried_on": "2021-08-23T23:35:51Z",
22
"db_created_on": "2021-08-23T23:35:51Z",
23
"columns": [...],
24
"popularity": {...},
25
"tags": [...],
26
"updated_on": "2021-08-23T23:35:51Z",
27
"created_on": "2021-08-23T23:35:51Z",
28
"table_type": "table",
29
"data_type": "table",
30
"bytes": 1024,
31
"row_count": 5
32
}
33
]
34
}
Copied!
You can find the guid for each table object in the "results" array.
As you can see from the response body, the /tables endpoint supports pagination for larger response sets.

Filtering by updated_on

The "results" table objects in the GET /tables/ endpoint (as seen in the previous subsection) contain a field updated_on, which reflects the last time a particular object was changed.
In order to see the latest changes to a set of metadata objects such as databases, schemas, tables, or columns, use the query parameter with the format updated_on__gte (i.e. for greater-than or equals). The gte can be replaced with lte, gt, lt as appropriate. As an example, see the docs for the tables endpoint.
Note that updated_on reflects the last change for an object (i.e. its description was changed or was ingested), but the field last_updated_on reflects the last time an object was ingested from the data source only.

Read a Table

With guids in hand, you can read the metadata of individual tables.
The endpoint is now:
1
GET /metadata/:guid/
Copied!
And the curl command would be:
1
curl -H "Authorization: Token <your_token>" https://api.production.selectstar.com/v1/metadata/<your_guid>/
Copied!
You should get back a response that looks like:
1
{
2
​
3
"object_type": "table",
4
"guid": "ta_UUyFgbgRhVqhhHa5WCjBaa",
5
"name": "sales",
6
"description": "global sales",
7
"search_name": "dwh.analytics.sales",
8
"data_type": "table",
9
"data_source_type": "snowflake",
10
"url": "string",
11
"tags": [
12
{
13
"guid": "ta_UUyFgbgRhVqhhHa5WCjBaa",
14
"type": "category",
15
"name": "Orders",
16
"icon": "tagBlue",
17
"color": "#33b1ff"
18
}
19
]
20
}
Copied!
That's it for reading from endpoints!

Write Descriptions to a Table

Writing is a little more involved than reading. Although the endpoint is the same, you'll need to tell your client to send a PATCH request, as well as a body of data that lets the Select Star API know what data to update with.
The endpoint is:
1
PATCH /metadata/:guid/
Copied!
and the payload is JSON (which may require you to set the content-type header as in the curl command):
1
{
2
"description": "new description here"
3
}
Copied!
Put together, the curl command is:
1
curl \
2
-H "Authorization: Token <your_token>" \
3
-H "content-type: application/json" \
4
--data '{"description": "global sales for last quarter"}' \
5
-X PATCH \
6
https://api.production.selectstar.com/v1/metadata/<your_guid>/
Copied!
The response will look just like the GET request response, except your description will have been updated.
1
{
2
​
3
"object_type": "table",
4
"guid": "ta_UUyFgbgRhVqhhHa5WCjBaa",
5
"name": "sales",
6
"description": "global sales for last quarter",
7
"search_name": "dwh.analytics.sales",
8
"data_type": "table",
9
"data_source_type": "snowflake",
10
"url": "string",
11
"tags": [
12
{
13
"guid": "ta_UUyFgbgRhVqhhHa5WCjBaa",
14
"type": "category",
15
"name": "Orders",
16
"icon": "tagBlue",
17
"color": "#33b1ff"
18
}
19
]
20
}
Copied!

Wrap-up

That's all for the basics of using the Select Star API! If you have any questions, please don't hesitate to reference the API documentation.