| ThoughtSpot Ation Thought Spot Administration Guide 4.4

User Manual: Pdf

Open the PDF directly: View PDF PDF.
Page Count: 311

Download| ThoughtSpot Ation Thought Spot Administration Guide 4.4
Open PDF In BrowserView PDF
Adminis
dministr
tra
ation Guide
Version 4.4, December 09, 2017

Copyright for ThoughtSpot publications. © 2017 ThoughtSpot, Inc. All rights
reserved.
ThoughtSpot, Inc. 1 Palo Alto Square
Building 1, Suite 200
Palo Alto, CA 94306
All rights reserved. This product is protected by U.S. and international copyright
and intellectual property laws. ThoughtSpot is a trademark of ThoughtSpot, Inc. in
the United States and/or other jurisdictions. All other marks and names mentioned
herein may be trademarks of their respective companies.

ThoughtSpot Administration Guide

December 09, 2017

Table of C
Cont
ontents
ents
Intr
Introduction
oduction tto
o adminis
administr
tra
ation
tion.....................................................................................................................................
.....................................................................................................................................5
5
Login cr
credentials
edentials ffor
or adminis
administr
tra
ation
tion.........................................................................................................................
.........................................................................................................................6
6
Understand the architecture

Ar
Archit
chitectur
ectural
al c
components
omponents.............................................................................................................................................
.............................................................................................................................................8
8
Da
Data
ta caching ........................................................................................................................................................................
........................................................................................................................................................................9
9
Authentica
uthentication
tion fr
frame
amew
works ........................................................................................................................................ 10
Da
Data
ta and object security
security................................................................................................................................................
................................................................................................................................................11
11
Perf
erformanc
ormance
ec
consider
onsidera
ations
tions.......................................................................................................................................
....................................................................................................................................... 13
Installation and setup

About ins
installa
tallation
tion and upgr
upgrades
ades..............................................................................................................................
.............................................................................................................................. 15
Set y
your
our locale
locale...................................................................................................................................................................
................................................................................................................................................................... 16
Tes
estt c
connectivity
onnectivity betw
between
een nodes .............................................................................................................................
.............................................................................................................................17
17
Set the rrela
elay
y hos
hostt ffor
or SMTP ........................................................................................................................................ 18
Set up a fiscal calendar y
year
ear ...................................................................................................................................... 19
Configur
onfigure
eS
SSL
SL...................................................................................................................................................................
...................................................................................................................................................................20
20
Configur
onfigure
eS
SAML
AML...............................................................................................................................................................
............................................................................................................................................................... 22
Integrate LDAP

About LD
LDAP
AP int
integr
egra
ation
tion.........................................................................................................................................
......................................................................................................................................... 23
Configur
onfigure
e LD
LDAP
AP ffor
or A
Activ
ctive
e Dir
Direct
ectory
ory .............................................................................................................. 24
Add the S
SSL
SL c
certifica
ertificatte ffor
or LD
LDAP
AP......................................................................................................................
...................................................................................................................... 26
Tes
estt the LD
LDAP
AP c
configur
onfigura
ation .................................................................................................................................
.................................................................................................................................2
27
Sync users and gr
groups
oups fr
from
om LD
LDAP
AP...................................................................................................................
................................................................................................................... 28
Configur
onfigure
e NA
NAS
S file ssy
ystem
em.....................................................................................................................................
.....................................................................................................................................30
30
Set up monit
monitoring
oring.......................................................................................................................................................
....................................................................................................................................................... 31
Configur
onfigure
e support servic
services
es...................................................................................................................................
................................................................................................................................... 32
Netw
Network
ork ports ............................................................................................................................................................. 36
About load balancing and pr
pro
oxies .................................................................................................................... 42
Load and manage data

Intr
Introduction
oduction tto
o da
data
ta management
management.........................................................................................................................
.........................................................................................................................44
44
Configur
onfigure
e casing .............................................................................................................................................................
.............................................................................................................................................................46
46
Load CS
CSV
V files with the UI
UI..........................................................................................................................................
.......................................................................................................................................... 47
Ho
How
w tto
o vie
view
w a da
data
ta schema ....................................................................................................................................... 51
Plan the schema

About schema planning ......................................................................................................................................... 54
Da
Data
ta types ..................................................................................................................................................................... 56

support@thoughtspot.com

i

ThoughtSpot Administration Guide

December 09, 2017

Cons
onstr
traints
aints .................................................................................................................................................................... 58
Shar
Sharding
ding .........................................................................................................................................................................
.........................................................................................................................................................................60
60
Chasm tr
traps
aps .................................................................................................................................................................
.................................................................................................................................................................64
64
Build the schema

Schema building o
ov
vervie
erview
w .................................................................................................................................... 67
Connect with T
TQL
QL and cr
crea
eatte a schema
schema........................................................................................................
........................................................................................................ 69
Ho
How
w tto
o writ
write
e a SQL script .......................................................................................................................................
.......................................................................................................................................7
71
Schema cr
crea
eation
tion e
ex
xamples ....................................................................................................................................
....................................................................................................................................7
72
Upload an SQL script
script...............................................................................................................................................
............................................................................................................................................... 75
Change the schema

Ho
How
w tto
o change a schema ...................................................................................................................................... 77
Con
onv
vert c
column
olumn da
data
ta type ....................................................................................................................................
....................................................................................................................................80
80
Load bulk data

Import CS
CSV
V files with tsload
tsload.................................................................................................................................
................................................................................................................................. 83
Use a script tto
o load da
data
ta........................................................................................................................................
........................................................................................................................................84
84
Delete a data source

Delet
Delete
e a da
data
ta sour
sourc
ce (table
(table)) ................................................................................................................................. 87
Delet
Delete
e or change a table in T
TQL
QL.........................................................................................................................
.........................................................................................................................90
90
Improve search with modeling

About da
data
ta modeling
modeling.....................................................................................................................................................
..................................................................................................................................................... 91
Change a table's da
data
ta model .................................................................................................................................... 92
Edit the ssy
ystem-wide da
data
ta model
model...........................................................................................................................
...........................................................................................................................94
94
Data model settings

Ov
Overvie
erview
w of the settings ........................................................................................................................................ 97
Set c
column
olumn name
name,, description, and type .......................................................................................................
.......................................................................................................99
99
Set additiv
additive
e and aggr
aggrega
egatte v
values
alues....................................................................................................................
....................................................................................................................10
1011
Hide a c
column
olumn or define a ssynon
ynonym
ym...............................................................................................................
............................................................................................................... 104
Change the inde
index
x type
type..........................................................................................................................................
.......................................................................................................................................... 106
Add a geogr
geographical
aphical da
data
ta setting ..................................................................................................................... 108
Set the sear
search
ch sugges
suggestions
tions priority
priority...................................................................................................................
................................................................................................................... 111
Set number
number,, da
datte, curr
currenc
ency
y fforma
ormats
ts .................................................................................................................
.................................................................................................................113
113
Change the A
Attribution
ttribution Dimension setting ...................................................................................................
...................................................................................................118
118
Link tables using relationships

Link tables using rrela
elationships
tionships .......................................................................................................................... 120
Delet
Delete
e a rrela
elationship
tionship................................................................................................................................................
................................................................................................................................................12
124
4
Use sstick
tickers
ers.......................................................................................................................................................................
.......................................................................................................................................................................126
126
Simplify search with worksheets

Cr
Crea
eatte and use w
worksheets
orksheets.......................................................................................................................................
.......................................................................................................................................129
129
Ho
How
w the inclusion rule w
works
orks ...................................................................................................................................
...................................................................................................................................134
134
Ho
How
w the w
worksheet
orksheet join rule w
works
orks.......................................................................................................................
.......................................................................................................................13
135
5

support@thoughtspot.com

ii

ThoughtSpot Administration Guide

December 09, 2017

Cr
Crea
eatte a fformula
ormula in a w
worksheet
orksheet ............................................................................................................................
............................................................................................................................13
137
7
Edit a w
worksheet
orksheet............................................................................................................................................................
............................................................................................................................................................ 140
Change inclusion, join, or RLS ffor
or a w
worksheet
orksheet...............................................................................................
...............................................................................................142
142
Delet
Delete
eaw
worksheet
orksheet or table .................................................................................................................................... 144
Manage users and groups

Unders
Understand
tand gr
groups
oups and privileges
privileges.......................................................................................................................
....................................................................................................................... 146
Cr
Crea
eatte, edit, or delet
delete
e a gr
group
oup................................................................................................................................
................................................................................................................................ 150
Add, edit, or delet
delete
e a user .........................................................................................................................................
.........................................................................................................................................155
155
Manage jobs

Job management ((scheduled
scheduled pinboar
pinboards
ds)) .........................................................................................................
.........................................................................................................15
159
9
Scheduled pinboar
pinboards
ds management
management.......................................................................................................................
.......................................................................................................................16
1611
Security

Ov
Overvie
erview
w of security ffea
eatur
tures
es..................................................................................................................................
..................................................................................................................................16
163
3
System Security
Security.............................................................................................................................................................
............................................................................................................................................................. 164
Data security

Da
Data
ta security
security...............................................................................................................................................................
...............................................................................................................................................................166
166
Shar
Share
e tables and c
columns
olumns.....................................................................................................................................
.....................................................................................................................................17
170
0
Shar
Share
ew
worksheets
orksheets......................................................................................................................................................
...................................................................................................................................................... 17
172
2
Shar
Share
e a pinboar
pinboard
d ....................................................................................................................................................... 17
174
4
Security ffor
or SpotIQ functions
functions.............................................................................................................................
.............................................................................................................................17
176
6
Revok
oke
e ac
acc
ces
esss (unshar
(unshare
e).......................................................................................................................................
.......................................................................................................................................177
177
Row level security (RLS)

About RLS
RLS....................................................................................................................................................................
....................................................................................................................................................................17
179
9
Ho
How
w Rule-Based RLS w
works
orks...............................................................................................................................
............................................................................................................................... 180
Set Rule-Based RLS
RLS.................................................................................................................................................
.................................................................................................................................................182
182
System administration

Ov
Overvie
erview
w of S
Sy
ystem adminis
administr
tra
ation
tion......................................................................................................................
......................................................................................................................186
186
System monit
monitoring
oring........................................................................................................................................................
........................................................................................................................................................18
187
7
Using the Spac
Space
e Utiliza
Utilization
tion chart
chart...........................................................................................................................
...........................................................................................................................19
193
3
Send logs when rreporting
eporting pr
problems
oblems...................................................................................................................
................................................................................................................... 194
Set up rrec
ecor
ording
ding ffor
or R
Repla
eplay
y Sear
Search
ch......................................................................................................................
......................................................................................................................196
196
Backup and restore

Unders
Understand
tand the back
backup
up sstr
tra
ategies
egies......................................................................................................................
......................................................................................................................200
200
Unders
Understand
tand back
backup/snapshot
up/snapshot schedules ........................................................................................................ 20
202
2
Work with snapshots ................................................................................................................................................. 205
Work with backups

Unders
Understand
tand back
backup
up modes ............................................................................................................................... 20
207
7
Cr
Crea
eatte a manual back
backup
up......................................................................................................................................
...................................................................................................................................... 209
Configur
onfigure
e periodic back
backups
ups ............................................................................................................................... 210
About rres
esttor
ore
e oper
opera
ations
tions......................................................................................................................................
......................................................................................................................................212
212

support@thoughtspot.com

iii

ThoughtSpot Administration Guide

December 09, 2017

Troubleshooting

About tr
troubleshooting
oubleshooting................................................................................................................................................
................................................................................................................................................213
213
Get logs
logs...............................................................................................................................................................................
...............................................................................................................................................................................214
214
Upload logs tto
oT
ThoughtSpot
houghtSpot Support
Support.................................................................................................................
.................................................................................................................216
216
Netw
Network
ork c
connectivity
onnectivity is
issues
sues.....................................................................................................................................
.....................................................................................................................................217
217
Change the time
timez
zone
one...................................................................................................................................................
...................................................................................................................................................218
218
Br
Bro
owser untrus
untrustted c
connection
onnection err
error
or ....................................................................................................................
....................................................................................................................219
219
Char
Charact
acters
ers not displa
displaying
ying c
corr
orrectly
ectly....................................................................................................................
.................................................................................................................... 220
Clear the br
bro
owser cache
cache.............................................................................................................................................
.............................................................................................................................................221
221
Cannot open a sa
sav
ved ans
answ
wer tha
thatt c
contains
ontains a fformula
ormula...............................................................................
...............................................................................223
223
Da
Data
ta loading ttoo
oo slo
slowly
wly.............................................................................................................................................
.............................................................................................................................................225
225
Sear
Search
ch rresults
esults c
contain
ontain ttoo
oo man
many
y blanks
blanks............................................................................................................
............................................................................................................226
226
About this rref
efer
erenc
ence
e....................................................................................................................................................
....................................................................................................................................................22
227
7
Keywor
ord
d rref
efer
erenc
ence
e .......................................................................................................................................................
.......................................................................................................................................................228
228
TQL rref
efer
erenc
ence
e .................................................................................................................................................................
.................................................................................................................................................................23
239
9
ThoughtSpot L
Loader
oader flag rref
efer
erenc
ence
e ................................................................................................................... 246
tscli c
command
ommand rref
efer
erenc
ence
e ...........................................................................................................................................
...........................................................................................................................................2
249
Da
Datte and time fforma
ormats
ts rref
efer
erenc
ence
e ......................................................................................................................... 264
Row le
lev
vel security rules rref
efer
erenc
ence
e ........................................................................................................................
........................................................................................................................26
267
7
Formula rref
efer
erenc
ence
e ........................................................................................................................................................
........................................................................................................................................................2
275
Err
Error
or c
code
ode rref
efer
erenc
ence
e ...................................................................................................................................................
...................................................................................................................................................285
285

support@thoughtspot.com

iv

Introduction to administration

December 09, 2017

Intr
Introduction
oduction tto
o adminis
administr
tra
ation
ThoughtSpot enables you to access and analyze your data through a search-based user interface. You can
create your searches on the fly by typing into a search bar, like you do when using an internet search
engine. ThoughtSpot makes it easy to see your data, get your questions answered, create interactive
graphs, and customize pinboards. You do not need to understand how the data is stored or know SQL to
do these things.
ThoughtSpot gives administrators the ability to modify data properties to meet business needs, for
example by providing search synonyms for common terms, boosting the importance of a column in search
results, or formatting how the data appears. Collaboration and security features make it easy for you to
protect sensitive data and for users to share information safely with others.
To perform the actions in this guide, you need administrative access.

ThoughtSpot Administration Guide

Page 5

Login credentials for administration

December 09, 2017

Login cr
credentials
edentials ffor
or adminis
administr
tra
ation
Summary: You need administrative access to perform the actions
discussed in this guide.
You can access ThoughtSpot via SSH at the command prompt and from a Web browser.

Adminis
dministr
tra
ativ
tive
e ac
acc
ces
esss
There are three separate default administrator users:
Login T
Type
ype

User

Acces
esss Method

Pas
assswor
ord
d

OS user

admin

SSH. Used for work that requires sudo or root
privileges. Does not exist for application login.

Contact
ThoughtSpot to obtain the default
password.

OS user

thoughtspot

SSH. Used for command line work that does
not require sudo or root privileges. Does not
exist for application login.

Contact
ThoughtSpot to obtain the default
password.

Application
user

tsadmin

Browser. Access through a Web browser and
for non-sudo or root privilege work

Contact
ThoughtSpot to obtain the default
password.

Both the admin and thoughtspot user can SSH into the appliance. Once on the appliance, either user can
do any of the following:
• tscli
• tsload
• tql
The thoughtspot user is restricted to tscli commands that do not require sudo or root privileges.

SSH tto
o the applianc
appliance
e
To perform basic administration such as checking network connectivity, starting and stopping services,
and setting up email, log in remotely as the Linux administrator user “admin”. To log in with SSH from any
machine, you can use the command shell or a utility like Putty.
In the following procedure, replace  with the hostname or IP address of a node in
ThoughtSpot. The default SSH port (22) will be used.
1. Log in to a client machine and open a command prompt.
2. Issue the SSH command, specifying the IP address or hostname of the ThoughtSpot instance:
ssh admin@

ThoughtSpot Administration Guide

Page 6

Login credentials for administration

December 09, 2017

3. Enter the password for the admin user.

Log in tto
o the T
ThoughtSpot
houghtSpot applica
application
tion
To set up and explore your data, access the ThoughtSpot application from a standard Web browser using
a username and password.
Before accessing ThoughtSpot, you need:
• The Web address (IP address or server name) for ThoughtSpot.
• A network connection.
• A Web browser.
• A username and password for ThoughtSpot.
Supported Web browsers include:
Br
Bro
owser

Version

Oper
Opera
ating S
Sy
ystem

Google Chrome

20 and above

Windows 7 or greater, Linux, MacOS

Mozilla Firefox

14 and above

Windows 7 or greater, Linux, MacOS

Internet Explorer

11

Windows 7 or greater

 Tip: While Internet Explorer is supported, using it is not recommended. Depending on your
environment, you can experience performance or UI issues when using IE.
To log in to ThoughtSpot from a browser:
1. Open the browser and type in the Web address for ThoughtSpot: http://
2. Enter your username and password and click Ent
Enter
er No
Now
w.

ThoughtSpot Administration Guide

Page 7

Architecture components

December 09, 2017

Ar
Archit
chitectur
ecture
ec
components
omponents
Summary: To implement ThoughtSpot it is important to understand
where it sits within your overall analytics architecture and how it
provides data to end users.
ThoughtSpot consists of a cluster of one or more nodes, acting together to provide analytic answers to
business questions. As such, there are only a few integration points with ThoughtSpot on your network.
The major components in the a ThoughtSpot cluster are:

ThoughtSpot can handle a wide variety of different data sources. ThoughtSpot does all analysis against
data in memory to help achieve fast results across millions and billions of records of data. ThoughtSpot
caches the data in order to process it.
The ThoughtSpot appliance can be a physical appliance that ThoughtSpot ships, one or more AWS
instances that are clustered together, or one or more VMware instances that are clustered together. From
an external interface, regardless of the appliance type, the appliance appears to be a single instance.
For authentication (logging in), some source of user information is required. These define the login
requirements and access control groups. Users will access the data from a supported browser to view
saved content or perform searched-based analytics. Finally, it is recommended that you have some sort of
networked attached storage for storing backups in case of hardware failure.

ThoughtSpot Administration Guide

Page 8

Data Caching

December 09, 2017

Da
Data
ta Caching
Summary: ThoughtSpot does all analysis against data in memory to
help achieve fast results across millions and billions of records of data.
ThoughtSpot caches data as relational tables in memory. The tables can be sourced from different data
sources and joined together. ThoughtSpot has four ways to get data into the cluster:

ThoughtSpot provides a JDBC and ODBC driver that can be used to write data to ThoughtSpot. This is
useful for customers who already have an existing ETL process or tool and want to extend it to populate
the ThoughtSpot cache.
Data Connect is a ThoughtSpot add-on that connects to a wide variety of data sources and pulls data into
ThoughtSpot.
You can use the tsload command line tool to bulk load delimited data with very high throughput. Finally,
individual users can upload smaller (< 50MB) spreadsheets or delimited files.
Which approach you use depends on your environment and data needs.
The following table shows the tradeoffs between different data caching options. Many implementations
use a variety of approaches. For example, a solution with a large amount of initial data and smaller daily
increments might use tsload to load the initial data and then use the JDBC driver with an ETL tool for
incremental loads.
JDBC/ODBC

Da
Data
ta C
Connect
onnect

• Have an ETL load,
for example, Informatica, SSIS, and
so forth.
• Have available resources to create
and manage ETL.
• Have smaller daily
loads.

ThoughtSpot Administration Guide

• Purchased as an add-on.
• Source data is well formed for
ThoughtSpot or it can be
modified prior to being
loaded.
• Have smaller daily loads.

tsload

• Initial data load.
• When JDBC/
ODBC and Data
Connect are not
options.
• When there are
large recurring
daily loads.
• Higher throughput but can add
I/O costs.

Page 9

Authentication

December 09, 2017

Authentica
uthentication
tion
Summary: ThoughtSpot does all analysis against data in memory to
help achieve fast results across millions and billions of records of data.
ThoughtSpot provides three ways to authenticate users LDAP/AD, SAML, and ThoughtSpot login. In
general, ThoughtSpot recommends that you use LDAP/AD or SAML if possible since ThoughtSpot
provides only basic authentication with no restrictions on passwords, timeouts, failed logins, etc.
The table below shows each of the options and the items to consider for each.
SAML

LD
LDAP
AP/AD
/AD

• Use SAML for
single sign-on
authentication.
• Can redirect
from
ThoughtSpot to
SAML logins.
• Recommended
for portal integration.
• Option to sync
users and
groups if stored
in LDAP/AD.

• Configuration.
• Users authenticate against
LDAP or AD.
• Option to sync users and
groups with ThoughtSpot
to manage group membership.

ThoughtSpot

• User created and
managed in
ThoughtSpot.
• No enterprise password control (expiration, password
strength, etc.).
• Only recommended
when SAML and
LDAP are not options.

All users and groups must be known to ThoughtSpot. If you are using LDAP/AD or SAML and don’t create
users in ThoughtSpot, a user is created when the user first logs in. However, this user is assigned to the
All group and will only see content available for all users.
Groups are the primary way that security is managed. Groups are not automatically created. You can
create groups and users manually or you need to automate the assignment from a source system.
ThoughtSpot has an assignment script that works with most LDAP / AD stores. It also has public APIs that
you can use to sync users and groups between source systems and your ThoughtSpot appliance.

ThoughtSpot Administration Guide

Page 10

Data and object security

December 09, 2017

Da
Data
ta and object security
Summary: Understand how to secure your data and other key
information in ThoughtSpot.
ThoughtSpot provides these features for protecting data security:
•
•
•
•

Object security
Row level security
Column level security
System privileges

Object Security
Object security is the ability for users to see content within ThoughtSpot. Objects can be tables, columns
in tables, worksheets, pinboards, and saved answers.
Users gain access to objects when an object owner share-answers with them. Owners can share with
individual users or with entire groups, giving access to anyone within that group. Owners can share with
edit or view options.
Currently, you cannot restrict someone who has had content shared with them from sharing with others.
Also, a user who belongs in a group can automatically share with anyone else in the group. This has
implications on setting up privileges and applying row level security.

Row le
lev
vel security (RLS)
Row level security controls what data a user can see in each shared piece of content. Even if a user has
access to a worksheet, for example, they can only see rows from the tables they have been given
permission to see.
RLS is applied at the table level and automatically applied every time. Also, in queries where there are
tables with table filters, all joins are always enforced, to avoid accidentally allowing users access to data
they shouldn’t see. RLS requires three things:
• A table filter with a column (possibly in a joined table) that can be used to determine who can
see a row, for example, account id or tenant id.
• A group that can be associated with the row of data by name. For example, if the column is
account_id and has values of 1, 2, 3, users can be assigned to groups group_1, group_2,
group_3 and then only see their data.
• Users must be assigned to the given group. If they are not assigned to a group that has access,
they do not see any data.
Administrative users can always see all rows of data since RLS is not applied for these users.
RLS supports a hierarchy of groups allowing you to give access to some users across multiple groups.
Keep in mind that users within a group can share with one another group. This means that putting
everyone into a company group for RLS means they can share with anyone in the company.

ThoughtSpot Administration Guide

Page 11

Data and object security

December 09, 2017

Column le
lev
vel security ((CLS)
CLS)
Column level security means only allowing users to see certain columns in a table. This can be
accomplished by only sharing certain columns with groups of users from a table.
However, most of the time users are given access to worksheets instead of columns. There is currently no
way to only share certain worksheet columns with certain groups. If you need this capability, you must
create different worksheets with the columns you want.
Also, note that because someone can share with anyone in a group they belong to, that means they could
potentially share restricted columns. For example, assume that HR has a column with salary information in
a worksheet that only HR has access to. An HR person could create an answer with the salary information
and share with someone outside of HR. That person would now have access to the salary information.
There are updates planned in future versions that will provider stricter access to columns and stronger
governance of data.

System privileges
System privileges refer to what a user can do in ThoughtSpot. For example, can they upload or download
data or share with all users. These privileges are defined on a group level and inherit downwards. So, if
Group A had child groups Group B and Group C, then any privilege given to Group A is also available to
Group B and Group C. What this often means is that separate sets of groups are required to manage
privileges.

ThoughtSpot Administration Guide

Page 12

Performance considerations

December 09, 2017

Perf
erformanc
ormance
ec
consider
onsidera
ations
Summary: Make sure you understand the performance considerations
in your installation.
ThoughtSpot is configured and licensed by memory availability. However, there are other considerations
that will impact the performance of your solution. It’s important to understand these considerations prior
to implementation, since some solutions will perform better than others.
Each node in a ThoughtSpot cluster has been found to perform ideally with less than 250GB of data and
fewer than .5 billion total rows of data. For schemas that are particularly complex, performance is
increased with even fewer rows of data per node. Ways to reduce the total amount of data and rows of
data include limiting the amount of data (number of years, etc.) or combining long, but narrow tables
together.

Da
Data
ta Boundaries
Total rows in a result of a join can also have an impact. In general, it is recommended that you have fewer
than 10 billion rows in a many-to-many join. Keep in mind these other boundaries:
Description

Boundary

Max number of rows that can be downloaded

10M (default is 1M)

Size in CSV format

1 TB per appliance

Total number of rows across all tables

2B per appliance

Many-to-Many (Generic) join cardinality

10B per appliance

Load frequency

Once every hour

Worksheet Boundaries
Worksheets must have less than 1000 columns. For aggregated worksheets, you should keep in mind the
following:
• Number of columns should be less than 50
• Number of rows should be less than 10 millions
You can use an ETL process to circumvent these limitations. Speak with ThoughtSpot Customer Support
to learn more.

Aggregated worksheets
To be able to join an aggregated worksheet with a base table, your installation must be configured to
allow the behavior. The aggregated worksheet cannot have more than 5 tables involved. Moreover, the
number of rows in the final aggregated worksheet cannot be greater than 1000.

ThoughtSpot Administration Guide

Page 13

Performance considerations

December 09, 2017

Chasm Trap worksheets
For chasm trap scenarios (two or more fact tables joined via a shared dimension) the following
boundaries are recommended:
Description

Boundary

Max number of fact tables in a worksheet

5

Max number of shared dimensions

2

Max number of rows in non co-sharded shared dimension table of chasm trap

10M

Max number of rows in co-sharded shared dimension table of chasm trap

1B

Row le
lev
vel security Boundaries
Max number of unique RLS rules with search data suggestions should not exceed 15K.

Da
Data
ta C
Connect
onnect Boundaries
The maximum number of connections should be less than or equal to 25.

Scheduled pinboar
pinboards
ds
For scheduled pinboards, ideal performance is to have 50 or fewer scheduled pinboard jobs.

ThoughtSpot Administration Guide

Page 14

About installation and upgrades

December 09, 2017

About ins
installa
tallation
tion and upgr
upgrades
ades
Your ThoughtSpot application software is already installed for you in a ThoughtSpot appliance (this is true
for both physical and virtual appliances). The ThoughtSpot software is updated by ThoughtSpot Support.
ThoughtSpot Support will contact you to schedule an update when one becomes available.
As administrator, you are responsible for setting up and configuring ThoughtSpot. This guide explains
how. It will also assist you in troubleshooting some common problems, finding additional resources, and
contacting ThoughtSpot.
To perform the set up and configuration, you must first learn how to gain administrative access. If you
haven’t already done this, do this now. Then, complete the following tasks as needed:
• Set y
your
our T
ThoughtSpot
houghtSpot locale
In addition to American English, ThoughtSpot also supports German and Japanese.
• Tes
estt netw
network
ork c
connectivity
onnectivity betw
between
een nodes
This procedure tests the network connectivity between the ThoughtSpot nodes, and to the LAN.
If you can perform these steps successfully, the network settings on ThoughtSpot are correct.
• Set the rrela
elay
y hos
hostt ffor
or SMTP ((email)
email)
To enable alert emails, you’ll need to set up a relay host for SMTP traffic from ThoughtSpot. This
routes the alert and notification emails coming from ThoughtSpot through an SMTP email server.
• Set up a fiscal calendar y
year
ear
Many companies start their fiscal calendar in a month other than January. If this is the case in
your company, setting a fiscal calendar quarter makes the ThoughtSpot date searches reflect
your fiscal year.
• Configur
onfigure
eS
SSL
SL ((secur
secure
e sock
socket
et la
lay
yers
ers))
You should use SSL (secure socket layers) for sending data to and from ThoughtSpot. SSL
provides authentication and data security. This section applies to both SSL to enable secure
HTTP and secure LDAP.
• Configur
onfigure
eS
SAML
AML
ThoughtSpot can use Security Assertion Markup Language (SAML) to authenticate users. You
can set up SAML through the shell on ThoughtSpot using a tscli based configurator.
• About LD
LDAP
AP int
integr
egra
ation
Some companies use LDAP (Lightweight Directory Access Protocol) to manage user
authentication. Using LDAP provides security and makes user management more centralized.
• Configur
onfigure
e a NA
NAS
S file ssy
ystem
Some operations, like backup/restore and data loading, require you to either read or write large
files. You can mount a NAS (network attached storage) file system for these operations.
• Configur
onfigure
e support servic
services
es
Set up and configure ThoughtSpot support services for your installation. You can designate a
support contact (email and phone number), set up a reverse tunnel to allow ThoughtSpot
Support to get access to your ThoughtSpot instance. Enable an optional “call home” capability
sends usage statistics to ThoughtSpot Support once a day via a secure file server.
• Set up monit
monitoring
oring
To configure monitoring of your cluster, set up the frequency of heartbeat and monitoring
reports and an email address to receive them.
• Netw
Network
ork ports
For regular operations and for debugging, there are some ports you will need to keep open to
network traffic from end users. Another, larger list of ports must be kept open for network traffic
between the nodes in the cluster.
• About load balancing and pr
pro
oxies
A load balancer is needed in front of a server group in order to direct traffic to individual servers
in a way that maximizes efficiency. Here are some of the best practices and guidelines for a
typical implementation with ThoughtSpot. Your experience may differ depending on your
environment and preference.

ThoughtSpot Administration Guide

Page 15

Set your ThoughtSpot locale

December 09, 2017

Set y
your
our T
ThoughtSpot
houghtSpot locale
Summary: You can change the language displayed in the application.
The language the ThoughtSpot UX displays is based off of the locale in a user’s profile. The locale
preferences control the language and data formats (date and number formats) by geographic locations. In
addition to American English (en-US), ThoughtSpot supports:
•
•
•
•

German (de-DE)
Japanese (ja)
Canadian English (en-CA)
United Kingdom English (en-GB)

So, if you set Japanese as your default locale in your profile settings, then the interface will update to
reflect that after you refresh your page.
Keywords, operators, and error messages are included in the translated material. Formulas, however, are
not translated. Also, all metadata remains as user inputted.

For example, if you are using ThoughtSpot in the US, the number formatting should look like this:
xxx,xxx.xx. And in Europe, it should look like this: xxx.xxx,xx.
 Warning: It is possible that you set your locale but find strings in the UI still appear in English, this
indicates an untranslated string. Please notify ThoughtSpot support.

ThoughtSpot Administration Guide

Page 16

Test network connectivity between nodes

December 09, 2017

Tes
estt netw
network
ork c
connectivity
onnectivity betw
between
een nodes
Summary: Verify your network is properly configured for the
application.
This procedure tests the network connectivity between the ThoughtSpot nodes, and to the LAN. If you
can perform these steps successfully, the network settings on ThoughtSpot are correct.
1. Log in to the Linux shell using SSH.
2. Ping each of the other nodes in the cluster.
3. Ping another machine that exists outside of the cluster, for example, a machine that you will use
to stage data to be loaded.
If you cannot perform these tests successfully, there is a problem with the network setup. If the tests fail,
check Network connectivity issues.

ThoughtSpot Administration Guide

Page 17

Set the relay host for SMTP (email)

December 09, 2017

Set the rrela
elay
y hos
hostt ffor
or SMTP ((email)
email)
Summary: To enable alert emails, you'll need to set up a relay host for
SMTP traffic.
ThoughtSpot uses emails for sending critical notifications to ThoughtSpot Support. A relay host for SMTP
traffic routes the alert and notification emails coming from ThoughtSpot through an SMTP email server.

Set up the rrela
elay
y Hos
Hostt
To set up a relay host:
1. Log in to the Linux shell using SSH.
2. Issue the setup command, providing the IP address of the relay host:
$ tscli smtp set-relayhost 
3. Verify your settings:
$ tscli smtp show-relayhost
4. Verify that email is working.

Configur
onfigure
e an email tto
o rrec
eceiv
eive
e alerts
ThoughtSpot sends alerts to the email address specified during installation. If no email address was
entered, no alerts are sent. You should add an email to receive alerts by issuing:
$ tscli monitoring set-config --email 
To send to multiple emails, provide a comma-separated list with no spaces.

Verify the rrela
elay
y with an email
Check if the email settings are working properly by using this procedure.
1. Log in to the Linux shell using SSH.
2. Try sending an email to yourself by issuing:
$ echo | mail -s Hello 
3. If you receive the email at the address(es) you supplied, email is working correctly.

ThoughtSpot Administration Guide

Page 18

Set up a fiscal calendar year

December 09, 2017

Set up a fiscal calendar y
year
ear
Summary: You can customize your fiscal calendar to start in month
other than January.
By default, the application’s fiscal calendar in January. If your company’s calendar year starts in another
month, setting a fiscal calendar quarter makes the ThoughtSpot date searches reflect your fiscal year.
When you set a custom fiscal year, you will designate the month on which your company’s fiscal year
begins. All the date language will then reflect your change, so if someone searches for this quart
quarter
er or q3
q3,
the answer will conform to the fiscal quarter in use. When you make this change, existing pinboards also
change to reflect the custom fiscal calendar. Because of this, if you make this change after your users have
been using ThoughtSpot for any period of time, you should alert them of the change you will be making
and how it affects previous saved searches.
Contact ThoughtSpot Support, so they can help you set the custom fiscal year.

ThoughtSpot Administration Guide

Page 19

Configure SSL

December 09, 2017

Configur
onfigure
eS
SSL
SL
Summary: SSL provides authentication and data security
You should use SSL (secure socket layers) for sending data to and from ThoughtSpot. SSL provides
authentication and data security. This section applies to both SSL to enable secure HTTP and secure
LDAP.

About S
SSL
SL
Many IT departments require SSL for their applications that access data. To use SSL with ThoughtSpot,
you’ll need your company’s own SSL certificate. The certificate is issued per domain, so if you want to use
SSL for both HTTP and LDAP, you will need two separate certificates - one for the HTTP domain and one
for the LDAP domain.
If you do not have an SSL certificate:
• Check with your IT department to see if they already have an SSL certificate you can use.
• If not, you will need to obtain the certificate from an issuing authority.
• Alternatively, you may disable SSL if you don’t want the security it provides by using the
command tscli ssl off.
There are many SSL vendors to choose from. Check with your existing Web hosting provider first, to see if
they can provide the certificate for you.
When you apply for the SSL certificate, you may specify a SAN, wildcard, or single domain certificate. Any
of these can work with ThoughtSpot.

Configur
onfigure
eS
SSL
SL ffor
or w
web
eb tr
traffic
affic
This procedure shows how to add SSL (secure socket layers) to enable secure HTTP (HTTPS) in
ThoughtSpot. To set up SSL, you will need:
• The SSL certificate
• The private key
To install the SSL certificate:
1. Follow the instructions from your certifying authority to obtain the certificate. This is usually
sent via email or available by download.
2. Copy the certificate and key files to ThoughtSpot:
$ scp   admin@:
3. Log in to the Linux shell using SSH.
4. Change directories to where you copied the certificate:
$ cd 
5. Issue the tscli command to install the certificate:

ThoughtSpot Administration Guide

Page 20

Configure SSL

December 09, 2017

$ tscli ssl add-cert  
6. To test that the certificate was installed correctly, Log in to the ThoughtSpot application.
You should see that the application’s URL begins with https://.

Set the rrec
ecommended
ommended TLS v
version
ersion
There are a couple of security vulnerabilities due to SSL certificates supporting older versions of TLS
(Transport Layer Security). This procedure shows you how to set the recommended TLS version to avoid
these vulnerabilities.
The PCI (Payment Card Industry) Data Security Standard and the FIPS 140-2 Standard require a minimum
of TLS v1.1 and recommends TLS v1.2.
ThoughtSpot supports SSL v3, TLS v1.0, and TLS v1.1 for backwards compatibility. However, the
recommended version is TLS v1.2. Therefore, to set the recommended TLS version:
1. Enable your web browser to support TLS v1.2. This can be done in your browser’s advanced
settings.
2. Log in to the Linux shell using SSH..
3. Issue the following command:
tscli security set-min-version 1.2
This will block all usage of older versions.

ThoughtSpot Administration Guide

Page 21

Configure SAML

December 09, 2017

Configur
onfigure
eS
SAML
AML
Summary: You can use the Security Assertion Markup Language
(SAML) to authenticate users
You can set up SAML through the shell on ThoughtSpot using a tscli based configurator.

Pr
Prer
erequisit
equisites
es
Before configuring SAML, you will need this information:
• IP of the server where your ThoughtSpot instance is running.
• Port of the server where your ThoughtSpot instance is running.
• Protocol, or the authentication mechanism for ThoughtSpot.
• Unique service name that is used as the unique key by IDP to identify the client.
It should be in the following format: urn:thoughtspot:callosum:saml
• Allowed skew time, which is the time after authentication response is rejected and sent back
from the IDP. It is usually set to 86400.
• The absolute path to the idp-meta.xml file. This is needed so that the configuration persists
over upgrades.
• This configurator also checks with the user if internal authentication needs to be set or not. This
internal authentication mechanism is used to authenticate tsadmin, so set it to true if you do
not know what it does.

Use tscli tto
oc
configur
onfigure
eS
SAML
AML
Use this procedure to set up SAML on ThoughtSpot for user authentication. Note that this configuration
persists across software updates, so you do not need to reapply it if you update to a newer release of
ThoughtSpot.
1. Log in to the Linux shell using SSH.
2. Execute the command to launch the interactive SAML configuration:
tscli saml configure
3. Complete the configurator prompts with the information you gathered above.
4. When the configuration is complete, open a Web browser and go to the ThoughtSpot login
page. It should now show the Single Sign On option.

ThoughtSpot Administration Guide

Page 22

About LDAP integration

December 09, 2017

About LD
LDAP
AP int
integr
egra
ation
Summary: You authenticate users against an LDAP server.
Some companies use LDAP (Lightweight Directory Access Protocol) to manage user authentication. Using
LDAP provides security and makes user management more centralized. You can choose to authenticate
users against an LDAP server, against ThoughtSpot, or both.
ThoughtSpot supports both anonymous and non-anonymous LDAP integration. Non-anonymous LDAP
binding is more rigorous than anonymous authentication, but it should help you track what your users are
querying and keep a log trace for auditing purposes.
If you have been using ThoughtSpot with users you created manually, and you now want to transition to
LDAP, please contact ThoughtSpot Support. They can assist you in migrating existing users to their LDAP
equivalents.
ThoughtSpot supports LDAP with Active Directory.

ThoughtSpot Administration Guide

Page 23

Configure LDAP for Active Directory

December 09, 2017

Configur
onfigure
e LD
LDAP
AP ffor
or A
Activ
ctive
e Dir
Direct
ectory
ory
Summary: Use this procedure to set up integration with LDAP using
Active Directory.
Before you configure LDAP for Active Directory, collect this information:
• URL to connect to Active Directory.
For example, ldap://192.168.2.48:389
• Default LDAP domain.
The default domain is the domain under which users who want to be authenticated against
Active Directory reside. When a user logs in with a username, the default domain is added to the
username before sending it to the LDAP server. If users reside in multiple domains, you can still
designate one of them as the default. Users belonging to a non-default domain will have to
explicitly qualify their username when they log in, for example:
username@ldap1.thoughtspot.com.
• Whether you will use SSL.
If yes, you’ll need the certificate from the issuing authority.
• LDAP search base.
This prompt adds the search base information that allows ThoughtSpot to find user properties
such as email and displayname from LDAP.
• Automatically add LDAP users in ThoughtSpot?
If you choose ‘yes’ for this, when a user is authenticated against LDAP, if that user does not exist
in ThoughtSpot, then the user is automatically created. When users are created in this way, their
passwords exist only in LDAP and are not stored in ThoughtSpot.
In order to log in to ThoughtSpot, the user has to exist in ThoughtSpot independent of whether
that user is authenticated against LDAP or against ThoughtSpot’s internal authentication. If you
choose ‘no’ for this, users who will authenticate against LDAP have to be manually created with
a dummy password as a placeholder in ThoughtSpot before they can log in. The username you
specify when creating the LDAP authenticated user manually in ThoughtSpot has to be domain
qualified, for example: username@ldap1.thoughtspot.com.
• Also use ThoughtSpot internal authentication?
If you choose ‘yes’ for this, when a user logs in, ThoughtSpot will first attempt to authenticate
the user against LDAP. If that attempt fails, it will then attempt to authenticate the user against
ThoughtSpot. If either of these succeed, then the user is successfully logged in. This option is
useful in scenarios where some users are not in LDAP and are created only in ThoughtSpot.
You do not need to create a user called tsadmin on your LDAP server. Internal authentication can be used
for tsadmin. To configure LDAP:
1. Log in to the Linux shell using SSH.
2. Run the command to configure LDAP:
$ tscli ldap configure
3. Answer the prompts using the information you collected. For example:
Choose the LDAP protocol:

ThoughtSpot Administration Guide

Page 24

Configure LDAP for Active Directory

December 09, 2017

[1] Active Directory
Option number: 1
Configuring Active Directory
URL to connect to Active Directory. (Example: ldap://192.168.2.100:389):
ldap://192.168.2.100:389
Default domain (Example: ldap.thoughtspot.com): ldap.thoughtspot.com
Use SSL (LDAPS) (y/n): n
LDAP search base (Example: cn=Users): cn=Users
Automatically add LDAP users in ThoughtSpot (y/n): y
Also use ThoughtSpot internal authentication (y/n): y
4. If you are using SSL, Add the SSL certificate for LDAP.
5. If you want to remove the LDAP configuration, issue:
$ tscli ldap purge-configuration

ThoughtSpot Administration Guide

Page 25

Add the SSL certificate for LDAP

December 09, 2017

Add the S
SSL
SL c
certifica
ertificatte ffor
or LD
LDAP
AP
Summary: Install the certificate to support LDAPS
When you set up LDAP, you specified whether or not to use SSL for LDAP (LDAPS). If using SSL, you
must install the LDAP SSL certificate. Before you can add the SSL certificate, you must Configure LDAP
for Active Directory.
You must have the SSL certificate before you start. For more information on obtaining an SSL certificate,
see Configure SSL (secure socket layers).
To add the SSL certificate for LDAP:
1. Follow the instructions from your certifying authority to obtain the certificate. This is usually
sent via email or available by download.
2. Copy the certificate to ThoughtSpot:
$ scp  admin@:
3. Log in to the Linux shell using SSH.
4. Change directories to where you copied the certificate:
$ cd 
5. Run the command to configure SSL for LDAP, designating an alias for this certificate using the
 parameter:
$ tscli ldap add-cert  

ThoughtSpot Administration Guide

Page 26

Test the LDAP configuration

December 09, 2017

Tes
estt the LD
LDAP
AP c
configur
onfigura
ation
Summary: This procedure allows you to test the LDAP connection you
created.
After configuring LDAP, you can test to make sure it is working by issuing a command.
1. Log in to the Linux shell using SSH.
2. Issue the LDAP testing command, supplying the information for the LDAP server you
configured, as in this example:
$ ldapsearch -x -h 192.168.2.61 -p 389 -D "testuser@ldap.thoughtspot.com" -W
-b "dc=ldap,dc=thoughtspot,dc=com" cn
3. Supply the LDAP password when prompted.
4. If the connection works, you’ll see a confirmation message.

ThoughtSpot Administration Guide

Page 27

Sync users and groups from LDAP

December 09, 2017

Sync users and gr
groups
oups fr
from
om LD
LDAP
AP
Summary: Use this procedure to synchronize your ThoughtSpot
system with an LDAP server.
Before synchronizing users and groups, you will need this information:
• IP address and port of the server where your ThoughtSpot instance is running. This hostport is
needed in the following format http(s)://: or http(s)://.
• Administrator login username and password for your ThoughtSpot instance.
• URL of the LDAP server, or hostport.
For example, ldap://192.168.2.48:389
• Login username and password for the LDAP system.
An example username would be moo_100@ldap.thoughtspot.com
• Distinguished Name (DN) for the base to start searching for users in the LDAP system.
For example, DC=ldap,DC=thoughtspot,DC=com
There are two ways for you to fetch users and groups from LDAP and populate them into your
ThoughtSpot system:
• Run the synchronization script in interactive mode, which will walk you through the process
(shown here).
• Create your own Python script by using the ThoughtSpot Python APIs. If you need details on
the Python APIs, contact ThoughtSpot Support. If you choose this method, you can run the
script periodically using a cron job.
To run the LDAP sync script in interactive mode:
1. Log in to the Linux shell using SSH.
2. Run the command to start the script:
python syncUsersAndGroups.py interactive
3. Answer the prompts using the information you collected above. For example:
Complete URL of TS server in format "http(s)://:":
http://10.77.145.24:8088
Disable SSL authentication to TS server (y/n): y
Login username for ThoughtSpot system: admin
Login password for ThoughtSpot system: 12345
Complete URL of server where LDAP server is running in format
ldap(s)://:: ldap://192.168.2.48:389
Login username for LDAP system: moo_100@ldap.thoughtspot.com
Login password for LDAP system: 12345
Syncs user and groups between LDAP and TS systems (y/n): y
Delete entries in ThoughtSpot system that are not currently in LDAP tree
being synced (y/n): n
Distinguished name for the base to start searching groups in LDAP System:
DC=ldap,DC=thoughtspot,DC=com
Scope to limit the search to (choice number)
0:base Searching only the entry at the base DN
1:one Searching all entries on level under the base DN - but not including
the base DN

ThoughtSpot Administration Guide

Page 28

Sync users and groups from LDAP

December 09, 2017

2:tree Searching of all entries at all levels under and including the
specified base DN: 2
Filter string to apply the search to: (|(CN=TestGroupAlpha)(CN=TestGroupBeta))
Answering this prompt is optional. If left blank, the default value of '(CN=*)'will be used.
Apply sync recursively, i.e. Iterates through group members and creates
member groups, users and relationships in a recursive way. (y/n): n
This prompt is asking if you would like to include group members even if they do not belong to
the current sub tree that is being synced.
4. Alternatively, to input your own shorthand script commands:
Issue the Python script commands, supplying all of the above information, following this format
example:
python syncUsersAndGroups.py script \
–-ts_hostport  \
--disable_ssl \
--ts_uname  \
--ts_pass  \
--ldap_hostport '' \
--ldap_uname '' \
--ldap_pass '' \
--sync \
--purge \
--basedn 'DC=ldap,DC=thoughtspot,DC=com' \
--filter_str '(|(CN=TestGroupAlpha)(CN=TestGroupBeta))' \
--include_nontree_members
The bottom half of the above command example targets sub trees under the DC called
TestGroupAlpha and TestGroupBeta, and iterates through them recursively to create/sync users,
groups, and their relationships in the ThoughtSpot system. It also deletes any other entities
created in the ThoughtSpot system from this LDAP system that are not currently being synced.

ThoughtSpot Administration Guide

Page 29

Configure NAS file system

December 09, 2017

Configur
onfigure
e NA
NAS
S file ssy
ystem
Summary: You can use network attached storage to support backup/
restore and data loading.
Some operations, like backup/restore and data loading, require you to either read or write large files. You
can mount a NAS (network attached storage) file system for these operations. Currently, ThoughtSpot
does not have an option for direct attached storage. Your NAS storage can use whichever drive format
you would like.
This procedure shows you how to mount a NAS file system for storing or accessing large files. The file
system will be mounted at the same location on each node in the cluster automatically. When any node is
restarted, the file system will be mounted again automatically, if it can be found.
When supplying a directory for writing or reading a backup, you can specify the mountpoint as the
directory to use. Likewise, you can stage data there for loading.
Backups are written by the Linux user admin. If that user does not have permission to write to the NAS file
system, you could write the backups to disk (for example /export/sdc1, /export/sdd1, /export/sde1,
or /export/sdf1) and then set up a cron job that executes as root user and copies the backup to the
NAS device every night, then deletes it from the directory.
Do not send the periodic backups or stage files on /export/sdb1 since it is a name node. It is used
internally by Hadoop Distributed File System (HDFS) and if this drive fills up, it can cause serious
problems. Do not allow backups or data files to accumulate on ThoughtSpot. If disk space becomes
limited, the system will not function normally.
1. Log in to the Linux shell using SSH.
2. Mount the directory to the file system, by issuing the appropriate command:
• For an NFS (Network File System) directory:
tscli nas mount-nfs
--server 
--path_on_server 
--mount_point 
• For a CIFS (Common Internet File System) directory:
tscli nas mount-cifs
--server 
--path_on_server 
--mount_point 
--username 
--password 
--uid 
--gid 
3. Use the mounted file system as you wish, specifying it by referring to its mount point.
4. When you are finished with it, you may optionally unmount the NAS file system:
tscli nas unmount --dir 

ThoughtSpot Administration Guide

Page 30

Set up monitoring

December 09, 2017

Set up monit
monitoring
oring
Summary: Setting up monitoring is a one time operation.
To configure monitoring of your cluster, set up the frequency of heartbeat and monitoring reports and an
email address to receive them.
1. Log in to the Linux shell using SSH.
2. Issue the tscli command to set up monitoring:
tscli monitoring set-config
--email 
--heartbeat_interval 
--report_interval 
The parameters are:
• --email  is a comma separated list (no spaces) of email addresses where the
cluster will send monitoring information.
• --heartbeat_interval  is the heartbeat email generation
interval in seconds. Must be greater than 0.
• --report_interval  sets the cluster report email generation
interval in seconds. Must be greater than 0.
3. To view your settings and verify that they have been applied, issue:
tscli monitoring show-config
You should see information like:
Monitoring Configuration:
Alert Email: dev-alerts@thoughtspot.com
Heartbeat Interval: 900 sec
Report Interval: 21600 sec
4. After the heartbeat interval has passed, check your email to verify that emails are being
delivered.
5. If you don’t receive any emails, verify that email is working.

ThoughtSpot Administration Guide

Page 31

Configure support services

December 09, 2017

Configur
onfigure
e support servic
services
es
Summary: Set up and configure ThoughtSpot support services for your
installation.
There are several configurations you can set up in your installation to ensure your company’s support from
ThoughtSpot works smoothly.

Set up a rre
everse tunnel ffor
or support
You can set up a reverse tunnel to allow ThoughtSpot Support to get access to your ThoughtSpot
instance, to perform support-related activities. This setup is a much simpler, more secure, and scalable
than the alternative option of using a virtual meeting room.
Granting remote support access can streamline troubleshooting activities, since it enables your support
agent to work directly in a secure setting. The remote tunnel enables SSH and HTTP access to your by
ThoughtSpot Support. This access can be granted and revoked easily, so you can enable it for a
troubleshooting session, and then disable it again. Before doing this procedure, make sure your company’s
security policies allow reverse tunneling.
Before you can do this procedure, your networking team needs to open port 22 in your firewall outgoing
rules.
To enable remote support:
1. Contact ThoughtSpot to open a support ticket for making the appropriate reverse tunnel
settings on our end. Provide the cluster name of the cluster for which you want to enable
remote support.
2. When the ticket has been completed, continue with the remaining steps in this procedure to
make the settings on your side.
3. Log in to the Linux shell using SSH.
4. Issue the command to configure the destination for the remote tunnel.
You only need to do this once, when you are enabling the tunnel for the very first time. After
that, this setting persists when you start and stop the remote tunnel.
$ tscli support set-remote --addr tunnel.thoughtspot.com --user ubuntu
5. Test that the setting has been applied:
$ tscli support show-remote
6. Enable the remote tunnel:
$ tscli support start-remote
7. Contact ThoughtSpot again, so you can test the setup with your ThoughtSpot Support contact.
8. After your remote session with ThoughtSpot Support, you should turn the remote tunnel off,
until you need to use it again:
$ tscli support stop-remote

ThoughtSpot Administration Guide

Page 32

Configure support services

December 09, 2017

You can repeat the steps to start and stop the remote tunnel as needed for future support
operations.
9. Test that the remote tunnel has been disabled:
$ tscli support show-remote

Configur
onfigure
e a secur
secure
e file serv
server
er
ThoughtSpot Support uses a secure file server to provide new releases and to receive logs and
troubleshooting files that you upload. The secure server connection is also required if you want to enable
the optional statistics collection using the call home feature.
Before you can upload a file to the secure file server, obtain your user name and password for logging in
to the secure file server. You can get these from ThoughtSpot Support.
Configuring the connection to the file server is a one time operation. You do not need to reconfigure the
connection unless your password changes. Note that you can do a one time override of the user and
password you used to configure the connection. This is done by passing a different user and password on
the command line when uploading or downloading a file.
To configure the connection to the secure file server:
1. Log in to the Linux shell using SSH.
2. Issue the command to configure the file server:
$ tscli fileserver configure --user  [--password ]
If you do not supply the --password parameter, you are prompted to enter it.

Enable call home capability
The optional “call home” capability sends usage statistics to ThoughtSpot Support once a day via a secure
file server.
Before you can enable the call home feature:
1. Configure the connection to the file server.
2. Obtain the customer name as recognized by the file server.
The customer name is formatted like this example: Shared//stats. If you do not know
the customer name, contact ThoughtSpot Support.
This can be helpful when troubleshooting problems with ThoughtSpot Support, because they will be able
to see basic usage information over time for your ThoughtSpot instance.
To set up the call home feature:
1. Log in to the Linux shell using SSH.
2. Enable the call home feature by issuing:
$ tscli callhome enable --customer_name 
3. If you want to disable call home in the future, you can do so by issuing:

ThoughtSpot Administration Guide

Page 33

Configure support services

December 09, 2017

$ tscli callhome disable

Designa
Designatte a support c
contact
ontact
A support contact person can answer questions for about data and searching at your company. If the
person can’t answer a question that person should submit system and software-related questions to
ThoughtSpot Support. Your designated support contact should have an available email and phone
number.
To designate the custom support contact:
1. Log in to the Linux shell using SSH.
2. Issue the tscli command to set the email address:
$ tscli support set-admin-email 
3. Issue the tscli command to set the phone number:
$ tscli support set-admin-phone 
4. If you need to reset both of these to the default (ThoughtSpot Support), issue:
$ tscli support rm-admin-email
$ tscli support rm-admin-phone

Ho
How
w users find y
your
our c
compan
ompany’
y’ss support c
contact
ontact
After you set the custom support contact information, here’s where your users will see it:
• In the Help Center, when they click Contact Support
Support.

ThoughtSpot Administration Guide

Page 34

Configure support services

December 09, 2017

• In error messages, when they click Wha
hatt Happened?

ThoughtSpot Administration Guide

Page 35

Network ports

December 09, 2017

Netw
Network
ork ports
Summary: Lists the required and optional ports for an installation.
For regular operations and for debugging, there are some ports you will need to keep open to network
traffic from end users. Another, larger list of ports must be kept open for network traffic between the
nodes in the cluster.

Requir
equired
ed ports ffor
or oper
opera
ations and debugging
The following ports need to be opened up to requests from your user population. There are two main
categories: operations and debugging.
Port

Pr
Prot
otoc
ocol
ol

Servic
Service
e
Name

Dir
Direction
ection

Sour
Sourc
ce

Des
Destina
tination
tion

Description

22

SSH

SSH

bidirectional

Administrators
IP addresses

All nodes

Secure shell access.
Also used for scp (secure copy).

80

HTTP

HTTP

bidirectional

All users IP
addresses

All nodes

Hypertext Transfer
Protocol for website
traffic.

443

HTTPS

HTTPS

bidirectional

All users IP
addresses

All nodes

Secure HTTP.

12345

TCP

Simba

bidirectional

Administrators
IP addresses

All nodes

Port used by ODBC
and JDBC drivers
when connecting to
ThoughtSpot.

2201

HTTP

Orion
master
HTTP

bidirectional

Administrator
IP addresses

All nodes

Port used to debug
the cluster manager.

2101

HTTP

Oreo
HTTP

bidirectional

Administrator
IP addresses

All nodes

Port used to debug
the node daemon.

4001

HTTP

Falcon
worker
HTTP

bidirectional

Administrator
IP addresses

All nodes

Port used to debug
the data cache.

4251

HTTP

Sage
master
HTTP

bidirectional

Administrator
IP addresses

All nodes

Port used to debug
the search engine.

ThoughtSpot Administration Guide

Page 36

Network ports

December 09, 2017

Netw
Network
ork P
Ports
orts
This reference lists the potential ports to open when setting up your security group.

Required ports for inter-cluster operation
Internally, ThoughtSpot uses static ports for communication between services in the cluster. Do not close
these ports from inter-cluster network communications. In addition, a number of ports are dynamically
assigned to services, which change between runs. The dynamic ports come from the range of Linux
dynamically allocated ports (20K+).
Port

Pr
Prot
otoc
ocol
ol

Servic
Service
e Name

Dir
Direction
ection

Sour
Sourc
ce

Des
Dest.
t.

Description

80

TCP

nginx

inbound

All nodes

All
nodes

Primary app HTTP
port (nginx)

443

TCP

Secure nginx

inbound

All nodes

All
nodes

Primary app
HTTPS port (nginx)

2100

RPC

Oreo RPC port

bidirectional

All nodes

All
nodes

Node daemon RPC

2101

HTTP

Oreo HTTP port

bidirectional

Admin IP
addresses
and all
nodes

All
nodes

Node daemon
HTTP

2181

RPC

Zookeeper servers
listen on this port
for client connections

bidirectional

All nodes

All
nodes

Zookeeper servers
listen on this port
for client connections

2200

RPC

Orion master RPC
port

bidirectional

All nodes

All
nodes

Internal communication with the
cluster manager

2201

HTTP

Orion master HTTP
port

bidirectional

Admin IP
addresses
and all
nodes

All
nodes

Port used to debug
the cluster manager

2210

RPC

Cluster stats service RPC port

bidirectional

All nodes

All
nodes

Internal communication with the
stats collector

2211

HTTP

Cluster stats service HTTP port

bidirectional

Admin IP
addresses
and all

All
nodes

Port used to debug
the stats collector

ThoughtSpot Administration Guide

Page 37

Network ports

Port

Pr
Prot
otoc
ocol
ol

December 09, 2017

Servic
Service
e Name

Dir
Direction
ection

Sour
Sourc
ce

Des
Dest.
t.

Description

nodes
2230

RPC

Callosum stats collector RPC port

bidirectional

All nodes

All
nodes

Internal communication with the BI
stats collector

2231

HTTP

Callosum stats collector HTTP port

bidirectional

Admin IP
addresses
and all
nodes

All
nodes

Port used to debug
the BI stats collector

2240

RPC

Alert manager

bidirectional

All nodes

All
nodes

Port where alerting
service receives
alert events

2888

RPC

Ports used by
Zookeeper servers
for communication
between themselves

bidirectional

All nodes

All
nodes

Ports used by
Zookeeper servers
for communication
between themselves

3888

RPC

Ports used by
Zookeeper servers
for communication
between themselves

bidirectional

All nodes

All
nodes

Ports used by
Zookeeper servers
for communication
between themselves

4000

RPC

Falcon worker RPC
port

bidirectional

All nodes

All
nodes

Port used by data
cache for communication between
themselves

4001

HTTP

Falcon worker
HTTP port

bidirectional

Admin IP
addresses
and all
nodes

All
nodes

Port used to debug
the data cache

4021

RPC

Sage metadata
service port (exported by Tomcat)

bidirectional

Admin IP
addresses
and all
nodes

All
nodes

Port where search
service contacts
metadata service
for metadata

4201

HTTP

Sage auto complete server HTTP
interface port

bidirectional

Admin IP
addresses
and all
nodes

All
nodes

Port used to debug
the search service

4231

HTTP

Sage index server
HTTP port

bidirectional

Admin IP
addresses
and all
nodes

All
nodes

Port used to debug
the search service

ThoughtSpot Administration Guide

Page 38

Network ports

December 09, 2017

Port

Pr
Prot
otoc
ocol
ol

Servic
Service
e Name

Dir
Direction
ection

Sour
Sourc
ce

Des
Dest.
t.

Description

4232

RPC

Sage index server
metadata subscriber port

bidirectional

All nodes

All
nodes

Port used for
search service internal communication

4233

RPC

Sage index server
RPC port

bidirectional

All nodes

All
nodes

Port used for
search service internal communication

4241

HTTP

Sage auto complete server HTTP
port

bidirectional

Admin IP
addresses
and all
nodes

All
nodes

Port used to debug
the search service

4242

RPC

Sage auto complete server RPC
port

bidirectional

All nodes

All
nodes

Port used for
search service internal communication

4243

RPC

Sage auto complete server metadata subscriber
port

bidirectional

All nodes

All
nodes

Port used for
search internal
communication

4251

RPC

Sage master RPC
port

bidirectional

All nodes

All
nodes

Port used for
search service internal communication

4405

RPC

Diamond
(graphite) port

bidirectional

All nodes

All
nodes

Port used for communication with
monitoring service

4500

RPC

Trace vault service
RPC port

bidirectional

All nodes

All
nodes

Trace collection for
ThoughtSpot services

4501

HTTP

Trace vault service
HTTP port

bidirectional

Admin IP
addresses
and all
nodes

All
nodes

Debug trace collection

4851

RPC

Graphite manager
RPC port

bidirectional

All nodes

All
nodes

Communication
with graphite manager

4852

HTTP

Graphite manager
HTTP port

bidirectional

Admin IP
addresses
and all
nodes

All
nodes

Debug graphite
manager

ThoughtSpot Administration Guide

Page 39

Network ports

December 09, 2017

Port

Pr
Prot
otoc
ocol
ol

Servic
Service
e Name

Dir
Direction
ection

Sour
Sourc
ce

Des
Dest.
t.

Description

4853

RPC

Elastic search
stack (ELK) manager RPC port

bidirectional

All nodes

All
nodes

Communication
with log search
service

4853

HTTP

Elastic search
stack (ELK) manager HTTP port

bidirectional

Admin IP
addresses
and all
nodes

All
nodes

Debug log search
service

5432

Postgres

Postgres database
server port

bidirectional

All nodes

All
nodes

Communication
with Postgres
database

8020

RPC

HDFS namenode
server RPC port

bidirectional

All nodes

All
nodes

Distributed file system (DFS) communication with
clients

8080

HTTP

Tomcat

bidirectional

All nodes

All
nodes

BI engine communication with
clients

8787

HTTP

Periscope (UI) service HTTP port

bidirectional

All nodes

All
nodes

Administration UI
back end

8888

HTTP

HTTP proxy server
(tinyproxy)

bidirectional

All nodes

All
nodes

Reverse SSH tunnel

11211

Memcached

Memcached server
port

bidirectional

All nodes

All
nodes

BI engine cache

12345

ODBC

Simba server port

bidirectional

All nodes

All
nodes

Port used for ETL
(extract, transform,
load)

50070

HTTP

HDFS namenode
server HTTP port

bidirectional

All nodes

All
nodes

Debug DFS metadata

50075

HTTP

HDFS datanode
server HTTP port

bidirectional

All nodes

All
nodes

Debug DFS data

Required ports for inbound and outbound cluster access
ThoughtSpot uses static ports for inbound and outbound access to a cluster.
Port

Pr
Prot
otoc
ocol
ol

Servic
Service
e
Name

Dir
Direction
ection

Sour
Sourc
ce

Des
Dest.
t.

Description

22

SCP

SSH

bidirectional

ThoughtSpot
Support

All
nodes

Secure shell access.

ThoughtSpot Administration Guide

Page 40

Network ports

December 09, 2017

Port

Pr
Prot
otoc
ocol
ol

Servic
Service
e
Name

Dir
Direction
ection

Sour
Sourc
ce

Des
Dest.
t.

Description

80

HTTP

HTTP

bidirectional

ThoughtSpot
Support

All
nodes

Hypertext Transfer Protocol
for website traffic.

443

HTTPS

HTTPS

bidirectional

ThoughtSpot
Support

All
nodes

Secure HTTP.

12345

TCP

Simba

bidirectional

ThoughtSpot
Support

All
nodes

Port used by ODBC and JDBC drivers when connecting
to ThoughtSpot.

Port

Pr
Prot
otoc
ocol
ol

Servic
Service
e
Name

Dir
Direction
ection

Sour
Sourc
ce

Des
Destina
tination
tion

Description

443

HTTPS

HTTPS

outbound

All nodes

208.83.110.20

For transferring files to
thoughtspot.egnyte.com (IP
address 208.83.110.20).

25
or
587

SMTP

SMTP
or Secure
SMTP

outbound

All nodes
and SMTP
relay
(provided
by customer)

All nodes

Allow outbound access for
the IP address of whichever
email relay server is in use.
This is for sending alerts to
ThoughtSpot Support.

389
or
636

TCP

LDAP
or
LDAPS

outbound

All nodes
and LDAP
server
(provided
by customer)

All nodes

Allow outbound access for
the IP address of the LDAP
server in use.

Required ports for IPMI (Intelligent Platform Management Interface)
ThoughtSpot uses static ports for out-of-band IPMI communications between the cluster and
ThoughtSpot Support.
Port

Pr
Prot
otoc
ocol
ol

Servic
Service
e
Name

Dir
Direction
ection

Sour
Sourc
ce

Des
Dest.
t.

Description

80

HTTP

HTTP

bidirectional

ThoughtSpot
Support

All
nodes

Hypertext Transfer Protocol
for website traffic.

Rela
elatted inf
informa
ormation
tion
EC2 Best Practices

ThoughtSpot Administration Guide

Page 41

About load balancing and proxies

December 09, 2017

About load balancing and pr
pro
oxies
Summary: A load balancer is needed in front of a server group in order
to direct traffic to individual servers in a way that maximizes efficiency.
Here are some of the best practices and guidelines for a typical implementation with ThoughtSpot. Your
experience may differ depending on your environment and preference.

Load balanc
balance
e acr
acros
osss T
ThoughtSpot
houghtSpot nodes
The following shows a network architectural diagram which includes a load balancer for ThoughtSpot
nodes.

The load balancer is an appliance in your infrastructure that routes traffic automatically to nodes to
provide failover. You can also place a load balancer or proxy in front of the ThoughtSpot appliance if you’d
like external network users to access the system.
The best way to load balance across all ThoughtSpot nodes in a cluster is to map one domain name
(FQDN) to all the IPs in the cluster in a round robin fashion.
For example, if you want to use a DNS server based load balancing, then you can define multiple “A”
resource records (RR) for the same name.
Below is an example of how you could set that up
thoughtspot.customer.com
thoughtspot.customer.com
thoughtspot.customer.com
thoughtspot.customer.com

IN
IN
IN
IN

A
A
A
A

69.9.64.11
69.9.64.12
69.9.64.13
69.9.64.14

The example indicates that IP addresses for the domain thoughtspot.customer.com are 69.9.64.11,
69.9.64.12, 69.9.64.13, and 69.9.64.14.

ThoughtSpot Administration Guide

Page 42

About load balancing and proxies

December 09, 2017

Ses
Session
sion A
Affinity
ffinity
Session Affinity refers to directing requests to the same application server for the time it takes to
complete a task.
In order for session affinity to work on ThoughtSpot, HTTPS (an SSL certificate) has to be installed on the
load balancer level. If it is installed outside of the load balancer, session affinity may not occur and the
ThoughtSpot system will fail.

Web pr
pro
oxies
You can access ThoughtSpot through any standard web proxy server. Web proxies are fairly universal
regardless of the application they are proxying. However, ThoughtSpot doesn’t use any new protocols, like
SPDY or HTTP/2, which may have a dependency on the proxy. Instead, ThoughtSpot is commonly placed
behind a web HTTP/HTTPS proxy.
Additionally, the proxy can round robin across multiple nodes in the ThoughtSpot backend. You can
essentially use the web proxy as a load balancer. Therefore, your session will carry over if the proxy round
robins between the ThoughtSpot backends as long as the URL doesn’t change.

ThoughtSpot Administration Guide

Page 43

Load and manage data

December 09, 2017

Load and manage da
data
ta
Summary: There are several methods of loading data into
ThoughtSpot. This section describes each method and why you might
choose it above the others.
The fastest and easiest way to load a new table is by importing it using the Web browser. This is best for
one time data loads of small tables which do not have complex relationships to other tables. This method
is limited to tables that are under 50 MB (megabytes) in size.
Using ThoughtSpot Loader, you can script recurring loads and work with multi-table schemas.
If your data already exists in another database with the schema you want to use in ThoughtSpot, you can
pull the schema and data in using the ODBC or JDBC driver.
These are the methods you can use to load data, along with the benefits of each method:
Method

Description

Benefits

Load data
from the
ThoughtSpot
UI

Use the ThoughtSpot Web interface to
upload an Excel or CSV (comma separated values) file from your local machine.

Easy way to do a one-time data load of
a small file (under 50MB).End users can
upload their own data and explore it
quickly.

Use
ThoughtSpot
Data Connect. For details, see the
ThoughtSpot
Data Connect
Guide

This is a premium feature, available at additional cost. Use ThoughtSpot Data Connect to connect directly to external data
sources and pull in tables and columns
from them. You can also set up recurring
loads to keep the data fresh.

Easy way to connect to multiple
sources of data directly and set up recurring loads. You won’t need to define
a schema to accept the data loads, because this is done automatically for
you.

Import with
the
ThoughtSpot
Loader
(tsload)

Use TQL and tsload to load data directly
into the back end database that
ThoughtSpot uses.

Best way to load large amounts of data
or a schema with multiple tables.Can be
scripted and used for recurring data
loads, such as monthly sales results or
daily logs. Can be integrated with an
ETL solution for automation.

Use the
ODBC/JDBC
driver to connect to
ThoughtSpot

Use the ODBC or JDBC client with your
ETL tool. For information, see the
ThoughtSpot Data Integration Guide.

Make use of an established ETL process
and tool(s).Connect to ThoughtSpot using third party tools like SSIS. You don’t
need to define a schema to accept the
data load.

Use the Informatica Connector

Use the Informatica Connector if you already use Informatica to connect to your
other data sources. For information, see
the ThoughtSpot Data Integration Guide.

Works with your established data migration processes in Informatica.

If you’re uploading data through the Web interface, you can use a native Excel file. If you want to use a
CSV (comma separated values) or delimited file, or you are loading using ThoughtSpot Loader, you’ll need
to create CSV files with the data to be loaded first.

ThoughtSpot Administration Guide

Page 44

Load and manage data

December 09, 2017

 Not
Note:
e: End users will almost always work with worksheets and data they upload.

Rela
elatted Inf
Informa
ormation
tion
•
•
•
•
•
•

Load CSV files with the UI
Append data through the UI
Schema planning concepts
Overview of schema building
Import CSV files with tsload
How to view a data schema

ThoughtSpot Administration Guide

Page 45

Configure casing

December 09, 2017

Configur
onfigure
e casing
Summary: You can set the type of case sensitivity you would like to see
reflected in the ThoughtSpot display.
Before you load your data, you should consider the type of casing you would like your data to reflect. The
case sensitivity for source data strings is preserved in the display. So, the visual display of results is
identical to the input case that is loaded.
 Not
Note:
e: The casing will remain lowercase in other parts of the application, such as when you ask a
question or filter.
It is important to note that string casings aren’t applied globally, but by column. So datasets will have
different string casings as long as they’re in different columns. Tables that are already compacted will keep
their lowercase format. In these cases, to get the specific string case that you want, you would have to
truncate related tables and reload them.
To take advantage of case configuration, you need to have ThoughtSpot Support enable it on your cluster
for you. In addition, title casing should be disabled for string casing to properly work.

ThoughtSpot Administration Guide

Page 46

Load CSV files with the UI

December 09, 2017

Load CS
CSV
V files with the UI
Summary: The simplest way to load data is to upload a CSV or Excel
file from the ThoughtSpot Web interface.
Loading data through the Web browser is recommended for smaller tables (under 50MB) with simple
relationships between them. This method is recommended for small, one time data loads. Using this
method, the data schema is created for you automatically.
Any user who belongs to a group that has the privilege Has adminis
administr
tra
ation privileges or Can upload user
da
data
ta can upload their own data from the browser.
Your data should be in a CSV (comma separated values) before you load it. A CSV file is a text file made
up of data fields separated by a delimiter and optionally enclosed with an enclosing character. If your data
contains multiple tables, you’ll have a separate CSV for each table.

Forma
ormatting
tting the CS
CSV
V
Your ETL (extract, transform, load) process will typically generate CSV files. You can also create a CSV file
from a Microsoft Excel spreadsheet by opening the spreadsheet in Excel, choosing Sa
Sav
ve As and selecting
CSV.
A CSV file contains a delimiter that marks the separation between fields in the data. The delimiter is
usually comma, but it can be any character. The file also contains fields optionally enclosed with double
quotes. Use these guidelines when creating the CSV file:
• If the CSV contains column headers, they must match the column names in the database exactly.
• Often a | (pipe) or tab is used as the delimiter, because it may be less likely to occur within the
data values.
• When a field contains a double quote, it must be escaped with the character specified in the
escape character argument in tsload.
• When a field contains the delimiter, the field must be enclosed in double quotes.
ThoughtSpot supports a wide range of date and timestamp formats in the CSV file. Blank values in user
uploaded CSV files are interpreted as NULL values. These include the values (case insensitive):
•
•
•
•
•

NULL
\N
NA
N/A
[space]

If you are appending data to an existing schema or table, columns in the CSV file must be in the same
order as defined in the target table.
If you are loading a fact table that joins to dimension tables, you must load the fact table first, and then
the dimension tables. The joining key must be a single column of unique values in the dimension table.
NULL values in the fact table cannot be joined.

Cr
Crea
eatte a CS
CSV
V file
The first step in loading data is to obtain or create one or more CSV files that contain the data to be
loaded into ThoughtSpot. CSV is a common format for transferring data between databases. ThoughtSpot
requires this format.
Most applications such as Microsoft Excel or Google Sheets can output CSV formatted files. If your source

ThoughtSpot Administration Guide

Page 47

Load CSV files with the UI

December 09, 2017

is an Excel spreadsheet or Google Sheet:
1. Save, export, or download the file in CSV format. The exact procedure you use will depend on
the source application.
2. Review the file’s format before uploading it to ThoughtSpot.
Your source data may be in another database. If this is the case, your company’s ETL (extract,
transform, load) process will typically generate CSV files. If your source is another database:
3. Connect to the source database.
4. Extract each table you wish to import into ThoughtSpot as a CSV file.
The column delimiter should be a , (comma), | (pipe), or tab.
For general information about CSV files and the rules for creating them, see the Comma-separated_values
on Wikipedia.

Load the CS
CSV
V File
Any user who belongs to a group that has the privilege Has adminis
administr
tra
ation privileges or Can upload user
da
data
ta can upload their own data from the browser. To load the CSV or Excel file into ThoughtSpot:
1. Log into ThoughtSpot from a browser.
2. Click on DATA, on the top navigation bar.

3. Click the Actions button in the upper right corner, and select Upload Da
Data
ta.

4. Upload the CSV or Excel file by doing one of these options:
a. Click on Br
Bro
owse y
your
our files and select the file.
b. Drag and drop the file into the drop area.
5. Answer the question Ar
Are
e the c
column
olumn names alr
already
eady defined in the file header?
6. Answer the question Ar
Are
e the fields separ
separa
ated b
by
y? Click Ne
Next
xt.
7. Click on the column header names to change them to more useful names, if you’d like. Click
Ne
Next
xt.

ThoughtSpot Administration Guide

Page 48

Load CSV files with the UI

December 09, 2017

8. Review the automatically generated data types for each column, and make any changes you
want. There are four data types: Text, Integer, Decimal, and Date.
9. Click Import
Import.
When an upload is complete, the system reports the results and offers you some further actions.

• Click Link tto
o Exis
Existing
ting Da
Data
ta if you want to link the data you uploaded to the data in
another table or worksheet.
• Click Sear
Search
ch if you want to begin a new search.
• Click Aut
uto
o analy
analyz
ze if you want to use the SpotIQ feature to find insights in your new
data.

Append tto
o an e
exis
xisting
ting table
You can append data to your existing system tables through the ThoughtSpot application, even if the
tables were initially loaded using Data Connect or tsload. The CSV file must have the same structure as
the table it is being loaded into, including number and type of columns, in the same order as the target
table.
To append data into ThoughtSpot:
1. Log in to ThoughtSpot from a browser.
2. Click on Da
Data
ta, on the top navigation bar.

3. Click the on the table you would like to append data to.
4. Click the Load da
data
ta button.

ThoughtSpot Administration Guide

Page 49

Load CSV files with the UI

December 09, 2017

5. Upload the CSV or Excel file by doing one of these options:
• Click on Br
Bro
owse y
your
our files and select the file.
• Drag and drop the file into the drop area.
6. Answer the question Ar
Are
e the c
column
olumn names alr
already
eady defined in the file header?
7. Answer the question Do y
you
ou w
want
ant tto
o append tto
o the e
exis
xisting
ting da
data
ta or o
ov
verwrit
erwrite
e it?
8. Answer the question Ar
Are
e the fields separ
separa
ated b
by
y? Click Ne
Next
xt.
9. Click on the column header names to change them to more useful names, if you’d like. Click
Ne
Next
xt.
10. Review the automatically generated data types for each column, and make any changes you
want. There are four data types: Text, Integer, Decimal, and Date.
11. Click Import
Import.
12. Click Link tto
o Exis
Existing
ting Da
Data
ta if you want to link the data you uploaded to the data in another table
or worksheet. Or click Sear
Search
ch if you want to begin a new search.

ThoughtSpot Administration Guide

Page 50

How to view a data schema

December 09, 2017

Ho
How
w tto
o vie
view
w a da
data
ta schema
Summary: Use the schema viewer to see tables and worksheets and
their relationships.
There is a schema viewer in ThoughtSpot which lets you see your database schema in the web browser.
The Schema Viewer is interactive, so you can configure it to show just what you want to see.
You need Admin or Da
Data
ta Management privilege to use the Schema V
Vie
iew
wer
er.

Bringing up the Schema V
Vie
iew
wer
You can access the Schema Viewer from the DATA screen by clicking Actions
ctions, and selecting Vie
iew
w Schema
Schema.

When viewing the schema, you can filter the tables shown similarly to how you filter data sources. The list
of tables, worksheets, and imported data on the left includes only those objects you want to see. Clicking
on one of the objects brings it to the middle of the viewer and highlights it. You can drag the objects
around in the viewer.

ThoughtSpot Administration Guide

Page 51

How to view a data schema

December 09, 2017

Why tto
o use the Schema V
Vie
iew
wer
You can use the Schema Viewer to find out information like:
• What is the relationship between two tables?
• What tables make up this worksheet, and how are they joined?
The schema viewer shows joins between tables, join directionality, and join type (whether they are Foreign
Key to Primary Key, relationship joins, or joins defined by users through the web interface). Use the Table
list to find a specific table or worksheet.

Worksheet vie
view
w
For worksheets, you can also click on one to view the worksheet. The worksheet view shows the following
information:
• All tables in the worksheet, and the relationships between these tables.
• Source columns for all columns of a worksheet.
• Keys and definitions for each relationship, as well as join paths and types.
• Columns that are derived from formulas.
• Correct join paths for newly created chasm trap worksheets. Existing chasm trap worksheets will
not show the correct join paths.

ThoughtSpot Administration Guide

Page 52

How to view a data schema

December 09, 2017

The worksheet view does not work for aggregated worksheets, but does works for worksheets built on
top of aggregated worksheets.

ThoughtSpot Administration Guide

Page 53

Schema planning concepts

December 09, 2017

Schema planning c
conc
oncepts
epts
Summary: Considerations in creating a schema for the ThoughtSpot
Loader.
Before you can load data with ThoughtSpot Loader, you must create a schema to receive it, using the SQL
command line interface (TQL).
The TQL syntax is similar to the SQL used in other relational databases, but with some important
differences. You’ll use DDL (data definition language) to create the schema into which you’ll load the data.
You’ll probably want to put all your DDL statements into a text file, which you’ll use as a script for creating
the schema.
Before writing your TQL script, you need to understand some basic ThoughtSpot concepts.

About da
databases
tabases and schemas
ThoughtSpot organizes objects in a hierarchical namespace. Databases contain schemas, which contain
tables.

ThoughtSpot can contain one or more databases, and each database can have multiple schemas. If you
do not specify a schema, the default schema (falcon_default_schema) is used automatically. This makes
it easier to add tables to the database without the need to explicitly create a schema.
If you do create an additional schema, you must refer to its objects using the syntax
.. If you do not qualify the schema when referencing its objects, the default
schema (falcon_default_schema) will always be assumed.
By default, ThoughtSpot creates an internal database to host tables corresponding to data that is
imported by users from a Web browser.

ThoughtSpot Administration Guide

Page 54

Schema planning concepts

December 09, 2017

Revie
view
w the sstructur
tructure
e of y
your
our da
data
ta
The schema you create to hold the data needs to be a good fit for your data. First, familiarize yourself with
the tables you want to load, and understand their structure. Make note of this information for each table:
•
•
•
•
•

The column names and data types
Type of table (fact or dimension)
Primary key column(s)
The size of the table on disk
Any other tables it can be joined with (foreign keys)

Here’s what you’ll need to take into account in your TQL for creating each table, based on these
properties:
Table type

Table
siz
size
e

To be
joined
with

Schema rrec
ecommenda
ommendations
tions

Fact

Any

Small dimension
table(s)

Sharded. Foreign key references the primary key in the dimension
table.

Fact

Any

Large dimension
table(s)

Sharded on the same distribution key as the dimension table it
will be joined with. Foreign key references the primary key in the
dimension table.

Fact

Any

Another
fact table

Sharded on the same distribution key as the fact table it will join
with. Many-to-many relationship defines how the tables will be
joined.

Dimension

under
50MB

Fact
table(s)

Replicated (not sharded). Has a primary key.

Dimension

over
50MB

Fact
table(s)

Distributed dimension table, sharded on the same distribution key
as the fact table it will be joined with. Primary key must be the
same as the distribution key.

Wher
here
e tto
o go ne
next
xt
• Da
Data
ta types
ThoughtSpot supports the common data types. Compare these with the data types you want to
load, and do any necessary conversion ahead of loading the data.
• Cons
onstr
traints
aints
Constraints include primary keys, foreign keys, and relationships. Relationships allow you to
create a generic relationship for use when you want to join tables that don’t have a primary key/
foreign key relationship.
• Shar
Sharding
ding
For the best performance, you should split (or shard) very large tables across nodes. If you have
a large dimension table, you might choose to co-shard it with the fact table it will be joined with.
• Chasm tr
traps
aps
In a complex schema, you may have a fact table with no relationship to another fact table,
except that each contains a foreign key to a shared dimension table. This is known as a chasm
trap, and ThoughtSpot can handle it!

ThoughtSpot Administration Guide

Page 55

Data types

December 09, 2017

Da
Data
ta types
Summary: ThoughtSpot supports the common data types.
Before you import data, compare the data types you want to load with these supported data types. Then,
convert your data before loading it. Typically, you would export the data, transform it to meet these type
rules, and then load the data. This is known as an extract-transform-load process.

Support
Supported
ed da
data
ta types
The tables you create to receive the data must have the same number of columns and data types as the
data you will be loading. Choose a data type for each column from the list of supported data types:
Da
Data
ta

Support
Supported
ed
da
data
ta types

Details

Character

VARCHAR(*n*)

Specify the maximum number of characters, as in VARCHAR(255). The
size limit is 1GB for VARCHAR values.

Floating
point

DOUBLE or
FLOAT

DOUBLE is recommended.

Boolean

BOOL

Can be true or false.

Integer

INT or BIGINT

INT holds 32 bits. BIGINT holds 64 bits.

Date or
time

DATE,
DATETIME,
TIMESTAMP,
TIME

DATETIME, TIMESTAMP, and TIME are stored at the granularity of seconds. TIMESTAMP is identical to DATETIME, but is included for syntax
compatibility.

 Warning: There is a 1GB limitation on the number of characters for VARCHAR. If you have any VARCHAR
data that exceeds this limit, the entire load will fail.

Geogr
Geographical
aphical da
data
ta types
For geographical data types, use VARCHAR. For latitude and longitude, you can use either VARCHAR or
DOUBLE. After loading the data, designate it as a geographical data type when you Edit the system-wide
data model. Wherever abbreviations or codes are used, they are the same as what the USPS (United
States Postal Service) recognizes.
These data types can be designated as geographical data, which enables them to be visualized using the
Geo chart types:
• Countries, for example:
◦ United States
▪ long name: United States
▪ name_sort: United States of America
▪ abbreviation: U.S.A.
▪ adm0_a3: USA
▪ adm0_a3_is: USA

ThoughtSpot Administration Guide

Page 56

Data types

•

•

•

•

•

•

December 09, 2017

▪ adm0_a3_us: USA
▪ admin: United States of America
▪ brk_a3: USA
▪ brk_name: United States
▪ formal_en: United States of America
▪ iso_a2: US
▪ iso_a3: USA
▪ iso_n3: 840
COUNTY for counties in the United States, for example:
◦ santa clara county
◦ pike county, ohio
◦ pike county, OH
STATE_PROVINCE for states in the United States, for example:
◦ name: California
◦ US Postal Service abbreviation: CA
LATITUDE which must be used with LONGITUDE, for example:
◦ 37.421023
◦ 1.282911
LONGITUDE which must be used with LATITUDE
◦ 122.142103
◦ 103.848865
ZIP_CODE for zip codes and zip codes +4 in the United States
◦ po_name: MT MEADOWS AREA
◦ ZIP: “00012”
◦ zip2: 12
Other Sub-nation Regions which are administrative regions found in countries other than the
United States, for example:
◦ bremen
◦ normandy
◦ west midlands
 Important: You cannot upload your own custom boundaries.

ThoughtSpot Administration Guide

Page 57

Constraints

December 09, 2017

Cons
onstr
traints
aints
Summary: Constraints allow you to build relationships and join tables.
Constraints include primary keys, foreign keys, and relationships. Relationships allow you to create a
generic relationship for use when you want to join tables that don’t have a primary key/foreign key
relationship.

Primary k
ke
eys
When a primary key is selected for a table, it impacts data loading behavior. When a new row is added:
• If another row already exists with same primary key, it is updated with the values in the new row.
• If a row with the same primary key does not exist already, the new row is inserted into the table.
This behavior is referred to as “upsert” because it does an INSERT or an UPDATE, depending on whether a
row with the same primary key already exists.
Note that ThoughtSpot does not check for primary key violations across different shards of the table.
Therefore, you need to shard the table on the primary key columns if you require this “upsert” behavior.

For
oreign
eign k
ke
ey rrela
elationships
tionships
Foreign key relationships help ThoughtSpot with default schema modeling by indicating a connection
between two tables. These relationships are used for joining the tables, and not for referential integrity
constraint checking. The foreign key relationship is defined on the fact table and references the primary
key(s) in the dimension table.
If you use primary and foreign keys, when users search the data from the search bar, tables are
automatically joined. For example, assume there are two tables:
• revenue, which is a fact table
• region, which is a dimension table
There is a foreign key on the fact table on regionid which points to the id in the region dimension table.
When a user types in “revenue by region”, the two tables will be joined automatically.
Foreign keys have to match the primary key of the target table they refer to. So if there are multiple
columns that make up the primary key in the target table, the foreign key must include all of them, and in
the same order.

Generic rrela
elationships
tionships (man
(many
y-t
-to-man
o-many)
y)
You may have a schema where there is a fact table that you want to join with another fact table. If there
isn’t a primary key/foreign key relationship between the tables, you can use many-to-many to enable this.
You can do this by using the RELATIONSHIP syntax to add a link between them, that works similarly to
the WHERE clause in a SQL join clause.
This is a special kind of relationship, that applies to specific data models and use cases. For example,
suppose you have a table that shows wholesale purchases of fruits, and another table that shows retail
fruit sales made, but no inventory information. In this case, it would be of some use to see the wholesale
purchases that led to sales, but you don’t have the data to track a single apple from wholesale purchase
through to sale to a customer.

ThoughtSpot Administration Guide

Page 58

Constraints

December 09, 2017

In a many-to-many relationship, the value(s) in a table can be used to join to a second table, using an
equality condition (required) and one or more range conditions (optional). These conditions act like the
WHERE clause in a SQL JOIN clause. They are applied using AND logic, such that all conditions must be
met for a row to be included.
To use a many-to-many relationship, you need to follow a few rules:
• There must be one equality condition defined between the two tables.
• Each table must be sharded on the same key that will be used for the equality condition.
• There can optionally be one or more range conditions defined.
This example shows the TQL statements that create the two fact tables and the relationship between
them.
TQL> CREATE TABLE "wholesale_buys" (
"order_number" VARCHAR(255),
"date_ordered" DATE,
"expiration_date" DATE,
"supplier" VARCHAR(255),
"fruit" VARCHAR(255),
"quantity" VARCHAR(255),
"unit_price" DOUBLE
)

PARTITION BY HASH (96) KEY ("fruit");

TQL> CREATE TABLE "retail_sales" (
"date_sold" DATE,
"location" VARCHAR(255),
"vendor" VARCHAR(255),
"fruit" VARCHAR(255),
"quantity" VARCHAR(255),
"sell_price" DOUBLE
)

PARTITION BY HASH (96) KEY ("fruit");

TQL> ALTER TABLE "wholesale_buys" ADD RELATIONSHIP WITH "retail_sales" AS
"wholesale_buys"."fruit" = "retail_sales"."fruit" and ("wholesale_buys"."date_ordered"
< "retail_sales"."date_sold" and "retail_sales"."date_sold" <
"wholesale_buys"."expiration_date");
 Not
Note:
e: A many-to-many implementation does not protect from over counting in some searches. If you
plan to use it, make sure your searches don’t include aggregation or count searches that will count one
value multiple times, because it satisfies the join condition for multiple rows.

ThoughtSpot Administration Guide

Page 59

Sharding

December 09, 2017

Shar
Sharding
ding
Summary: Sharding partitions very large tables into smaller, faster,
more easily managed parts called data shards.
ThoughtSpot tables can be replicated or sharded. Replicated tables exist in their entirety, the complete
data set, on each node. Sharded tables consist of a single data set divided into multiple tables or shards.
The shards have identical schemas but different sets of data.
By default, ThoughtSpot tables are replicated, you must explicitly shard tables. Sharding your tables
impacts the total amount of memory used by the table as well as its performance.
For example, you might shard a large table of sales data. So, you could divide a single sales table into
shards each of which contains only the data falling within a single year. These shards are then distributed
across several nodes. Requests for sales data are dispersed both by the year and the location of the shard
in the node cluster. No single table or node is overloaded, and so the performance of a query and the
system load are both improved.
To optimize ThoughtSpot performance, you should shard very large fact tables whenever possible. If you
have a large dimension table, you might choose to shard it along with the fact table it is joined with.
Sharding both the fact and dimension table is known as co-sharding.

Ho
How
w tto
o shar
shard
d
Sharding is a type partitioning and is sometimes called Horizontal partitioning. The term sharding is
particular to situations where data is distributed not only among tables but across nodes in a system. To
create a sharded table add the add PARTITION BY HASH ( ) clause to your CREATE TABLE statement.
TQL> CREATE TABLE ...
...PARTITION BY HASH (96) KEY ("customer_id");
The HASH parameter determines the number of shards and the KEY parameter the sharding key. The
recommended number of shards depends upon the number of nodes in your cluster:
Number of Nodes

Number of Shar
Shards
ds

1

32

2

64

3

96

4-12

128

13-24

256

25-36

384

37-48

512

49-60

640

ThoughtSpot Administration Guide

Page 60

Sharding

December 09, 2017

Number of Nodes

Number of Shar
Shards
ds

61-72

768

If you omit the PARTION BY HASH statement or if the HASH parameter is 1 (one), the table is unsharded.
This also means the table physically exists in its entirety on each node.
If you want to use the primary key for sharding, specify that the table is to be partitioned by HASH on the
primary key, as in this example:
TQL> CREATE TABLE "supplier" (
"s_suppkey" BIGINT,
"s_name" VARCHAR(255),
"s_address" VARCHAR(255),
"s_city" VARCHAR(255),
"s_phone" VARCHAR(255),
CONSTRAINT PRIMARY KEY ("s_suppkey")
) PARTITION BY HASH (96) KEY ("s_suppkey");
The system does not use primary keys as sharding keys by default. If you specify the PARTION BY HASH
statement with a HASH greater than 1 (one) but omit the KEY parameter ThoughtSpot shards the table
randomly. This is not recommended; avoid this by always ensuring you specify the KEY parameter with a
HASH greater than 1 (one).

Ho
How
w tto
o choose a shar
shard
dk
ke
ey
When you shard a large table, you select a shard key from the table. This key exists in every shard. You can
use any data type that is valid for use as the primary key as the shard key. Choosing a shard key plays an
important role in the number of shards and the size of any single shard.
A shard key should contain a value that has a good distribution (roughly the number of rows with each
value in that column). This value is typically part of the primary key, but it can include other columns. For
example:
CREATE TABLE "sales_fact"
("saleid" int,
"locationid" int,
"vendorid" int,
"quantity" int,
"sale_amount" double,
"fruitid" int,
CONSTRAINT
PRIMARY KEY("saleid,vendorid"))
PARTITION BY HASH(96)
KEY ("saleid");
Notice the shard key contains the saleid value that is also part of the primary key. When creating a shard
key use these guidelines.
• Include one or more values of the table’s primary key in the shard key.
This prevents scenarios where the data with the same primary key ends up in different shards
and nodes because the shard key changed.
• If you expect to join two tables that are both sharded, make sure both tables use the same shard
key.
This guideline ensures better join performance. So, for example, if you have two tables and the
primary keys are:

ThoughtSpot Administration Guide

Page 61

Sharding

December 09, 2017

PRIMARY KEY("saleid,vendorid") on A PRIMARY KEY("saleid,custerid") on B
You should use saleid for your shared key when you shard both table A and B.
• Choose a shard key so that the data is distributed well across the keys.
For example, suppose the table you want to shard has a primary key made up of
saleid,custid,and locationid. If you have 10K sales but 400 locations, and 2000 customers,
you would not want to use the locationid in your shard key if 5k sales were concentrated in
just 2 locations. The result would be data in fewer shards and degrade your performance.
Instead, your shard key may be custid,and locationid.
• Choose a shard key that results in a wide variety of keys.
For example, suppose the table you want to shard has a primary key made up of
saleid,productid,and locationid. Suppose the table has 10K sales, 40 locations, and 200
products. If the sales are evenly distributed across locations you would not want to use the
locationid in your shard key. Instead, saleid and productid would be the better choice as it
results in a wider variety of keys.
as mentioned in the previous section, it is possible to simply use the primary key as a shard key.

Shar
Sharded
ded dimension tables
In a typical schema, you’d have a sharded fact table with foreign keys to small dimension tables. These
small dimension tables are replicated in their entirety and distributed on every node. This works best
where dimension tables under 50MB in size.
If you have a large dimension table, replicating it and distributing it can impact the performance of your
ThoughtSpot System. In this case, you want to shard the dimension tables and distribute it the same way
as the fact table it joins to.
When sharding both a fact and its dimension table (known as co-sharding) keep in mind the guidance for
creating a shard key. Only shard dimension tables if the dimension table is large (over 50MB) and the join
between the fact and dimension tables use the same columns. Specifically, the tables must:
• be related by a primary key and foreign key
• be sharded on the same primary key/foreign key
• have the same number of regions (or shards)
If these requirements are met, ThoughtSpot automatically co-shards the tables for you. Co-sharded tables
are always joined on the sharding key. Data skew can develop if a very large proportion of the rows have
the same sharding key.
This example shows the CREATE TABLE statements that meet the criteria for sharding both a fact table
and its dimension table:
TQL> CREATE TABLE products_dim (
"id" int,
"prod_name" varchar(30),
"prod_desc" varchar(100),
PRIMARY KEY ("id")
)
PARTITION BY HASH (96) KEY ("id")
;
TQL> CREATE TABLE retail_fact (
"trans_id" int,
"product_id" int,
"amount" double,
FOREIGN KEY ("product_id") REFERENCES products_dim ("id")
)
PARTITION BY HASH (96) KEY ("product_id")
;

ThoughtSpot Administration Guide

Page 62

Sharding

December 09, 2017

If a dimension table is joined to multiple fact tables, all of the fact tables must be sharded in the same way
as the dimension table. Self-joins are not supported.

Joining tw
two
o shar
sharded
ded ffact
act tables
You can also join two sharded fact tables with different shard keys, this is known as non co-sharded tables.
It may take a while to join two tables sharded on different keys since a lot of data redistribution is
required. Therefore, ThoughtSpot recommends that you use a common shard key for two fact tables.
You are not limited by the column connection or relationship type.

ThoughtSpot Administration Guide

Page 63

Chasm traps

December 09, 2017

Chasm tr
traps
aps
Summary: A chasm trap occurs when two many-to-one joins converge
on a single table.
In a complex schema, you may have a fact table with no relationship to another fact table, except that
each contains a foreign key to a shared dimension table. This is known as a chasm trap, and ThoughtSpot
can handle it!

Unders
Understand
tand ho
how
w chasm tr
traps
aps oc
occur
cur
A fact table, just as it sounds, stores facts about your business. If you are selling applies, the sales fact
table has facts about these apples.
SaleID

AppleT
AppleTypeID
ypeID

Stor
oreID
eID

Units Sold

4

55

2

12

8

34

33

3

10

09

09

1

Dimension tables describe the attributes that are interesting to analyze. For example, the apple table
might look like this.
AppleT
AppleTypeID
ypeID

Color

Name

Use

55

Red

Red Delicious

Snack

34

Green

Granny Smith

Cooking

09

Yellow

Golden

Snack

As you can imagine, in a business you might have several fact tables that access dimension tables. So, an
apple business may record waste as well as sales.
TimeID

AppleT
AppleTypeID
ypeID

Stor
oreID
eID

Units W
Was
astted

4

55

2

2

8

34

33

43

10

09

09

11

Both the sales and waste tables are facts that reference the apple dimension table.
A chasm trap in a data schema can introduce problems of over counting if you join the two fact tables
through their shared dimension table. This diagram shows a typical complex schema with several tables
that are related over a chasm trap:

ThoughtSpot Administration Guide

Page 64

Chasm traps

December 09, 2017

Examples of use cases where a chasm trap could occur when attribution analysis compare campaign data
with purchase data, where all they have in common is that both contain a customer identifier that is a
foreign key to a customer dimension table. Chasm traps also occur, for example, in cost of sales analysis
when wholesale orders data is only related to the retail sales data through a shared products dimension
table.
In many databases, joining tables across a chasm trap creates a Cartesian product or cross join. That is
each row from the first fact table is joined to each row from the second table. A Cartesian product causes
over counting when computing counts and aggregates. ThoughtSpot protects you from this kind of over
counting.
There are still just a few things to look out for when using a schema that contains chasm traps:
• The tables should be joined to the dimension table via an equi-join (i.e. a primary key/foreign key
relationship). They cannot be joined using a range of values.
• Review the column setting called Attribution Dimension. You may need to change this setting if
some of the columns in the shared dimension table should not be used for attribution when
combining fact tables.
• Tables that will be joined across a chasm trap do not need to be co-sharded. They will be joined
appropriately automatically in the most efficient way.

Chasm tr
trap
ap limita
limitations
tions
If your database schema contains any chasm traps, you may encounter these limitations.

Operations
The following limitations on chasm trap schemas will produce a red bar error in the ThoughtSpot
application:
• Sho
Show
w underlying da
data
ta does not work for chasm trap searches, whether the search is on a
worksheet containing a chasm trap or on base tables that are related over a chasm trap.
• When using the ThoughtSpot APIs, you cannot pass filter values via the URL if the relevant

ThoughtSpot Administration Guide

Page 65

Chasm traps

December 09, 2017

searches occur on a worksheet containing a chasm trap or on base tables that are related over a
chasm trap.
• UseRule-Based Row Level Security.

Behavior
The following behavior is different for chasm traps than for schemas that do not contain a chasm trap:
• There are no headlines (single facts based on the data) shown when a search contains a
worksheet containing a chasm trap or base tables that are related over a chasm trap.
• Join information in Wha
hatt am I L
Looking
ooking A
At?
t? does not appear for searches on a worksheet
containing a chasm trap or on base tables that are related over a chasm trap.
• There are cases when attempting to configure certain charts on chasm trap worksheets or
tables will not work. If this happens, you will see the error Your sear
search
ch needs tto
o ha
hav
ve unique y
y-axis v
values
alues ffor
or each series of da
data
ta sho
shown
wn on the x
x-axis
-axis. The workaround is to remove all columns
from the search, except for those used in your chart.

Workarounds
In some cases, there is a workaround of saving an answer as a worksheet (Aggregated Worksheet). See
the ThoughtSpot User Guide for details on how to do this. If you save a chasm trap search as a worksheet,
it becomes a materialized view of the answer. Effectively, it is then just a regular table (no chasm trap). As
such, most of the issues above will not affect searches on the saved worksheet.

ThoughtSpot Administration Guide

Page 66

Overview of schema building

December 09, 2017

Ov
Overvie
erview
w of schema building
Summary: Before you can load data into ThoughtSpot, you must build
a database schema to receive it.
You can build a schema by writing a SQL script that creates the objects in your schema. ThoughtSpot
provides the ThoughtSpot SQL Command Line (TQL) for creating, viewing, and managing a schema using
SQL. Your script can use any statements that are supported in ThoughtSpot SQL Command Line (TQL).
The TQL syntax is similar to the SQL used in other relational databases, but with some important
differences.
You’ll use DDL (data definition language) to create the schema into which you’ll load the data. You’ll
probably want to put all your DDL statements into a text file, which you’ll use as a script for creating the
schema.

Upload the script thr
through
ough the br
bro
owser
You can upload an your SQL script directly through the browser in the ThoughtSpot application. You can
edit the script or add to it right within the browser, too. The steps to build a schema through the browser
are:
1. Write a SQL script to create the schema
2. Import a schema (use the SQL editor)

Use T
TQL
QL on the SQL c
command
ommand line
You can choose to run your SQL script within the Linux shell instead. You can run TQL in interactive
command line mode, or you can write a script and use TQL to run it. The SQL syntax in ThoughtSpot is
called TQL for ThoughtSpot SQL. The ThoughtSpot SQL Command Line (TQL) runs in an interactive
mode. To invoke TQL Log in to the Linux shell using SSH and type tql. At the prompt, type h or help to
see a list of supported commands.
The steps to build a schema using TQL include:
1. Connect to the database with the ThoughtSpot SQL Command Line (TQL).
2. Write a SQL script to create the schema.
3. Type your SQL commands on the command line, terminating each command with a semicolon
(;).
Commands can span multiple lines. ThoughtSpot supports a limited number of SQL commands,
plus some custom SQL extensions. For example, you can specify the number of shards and the
distribution key as part of the CREATE TABLE syntax. A full list of supported SQL in TQL is
available in the TQL reference.

Wher
here
e tto
o go ne
next
xt
• Connect with T
TCL
CL and cr
crea
eatte a schema
Having examined the structure of the data to be loaded and become familiar with the
ThoughtSpot SQL Command Line (TQL), you are now ready to create the schema.
• Writ
rite
e a SQL script tto
o cr
crea
eatte the schema
Using a SQL script to create your schema is a recommended best practice. This makes it easier
to adjust the schema definitions and recreate the schema quickly, if needed.

ThoughtSpot Administration Guide

Page 67

Overview of schema building

December 09, 2017

• Schema cr
crea
eation
tion e
ex
xamples
These examples demonstrate the steps involved in creating a schema using the ThoughtSpot
SQL Command Line (TQL). After the schema is created, you can load data into it with
ThoughtSpot Loader.
• Upload and run a SQL script)
You can run a SQL script to create your database schema through the browser, without having
to log in to the shell on the ThoughtSpot instance. You can edit the script and run it directly in
the browser to create the schema.

ThoughtSpot Administration Guide

Page 68

Connect with TCL and create a schema

December 09, 2017

Connect with T
TCL
CL and cr
crea
eatte a schema
To perform administrative tasks directly in the database, you will use the ThoughtSpot SQL Command
Line (TQL). TQL supports many, but not all, common SQL commands.

Connect with T
TQL
QL
Before connecting with TQL, you will need:
• Access to your ThoughtSpot instance Linux shell from a client machine.
• The administrator OS login.
To connect to TQL:
1. Log in to the Linux shell using SSH.
2. Invoke TQL:
$ tql
TQL>
3. Enter your SQL command, followed by a semicolon (;).

Ent
Enter
er a SQL script
Having examined the structure of the data to be loaded and become familiar with the ThoughtSpot SQL
Command Line (TQL), you are now ready to create the schema.
This method is a good way to get familiar with TQL and how to create database objects, but when
creating a schema in a production system, you will most likely Write a SQL script to create the schema.
To create the schema directly in TQL:
1. Connect to the database with the ThoughtSpot SQL Command Line (TQL).
2. If the database you will be using does not exist, create it now:
TQL> CREATE DATABASE my_database;
3. Connect to the database:
TQL> USE my_database;
4. If you wish to use a schema other than the default one, create it now:
TQL> CREATE SCHEMA my_schema;
5. Issue a CREATE TABLE command for each table you will create, using the information in Plan the
schema.

ThoughtSpot Administration Guide

Page 69

Connect with TCL and create a schema

December 09, 2017

 Tip: Foreign key declaration within a CREATE TABLE will show the table created even if there
are problems with the foreign key. Therefore, it is good practice to also issue a separate ALTER
TABLE ADD CONSTRAINT FOREIGN KEY command.

ThoughtSpot Administration Guide

Page 70

How to write a SQL script

December 09, 2017

Ho
How
w tto
o writ
write
e a SQL script
Summary: Using a SQL script to create your schema is a
recommended best practice. This makes it easier to adjust the schema
definitions and recreate the schema quickly, if needed.
The schema creation script is a text file that contains all the SQL commands to create your schema.
Comments should be enclosed in the comment tags /* and */.
Enclose all object names (schema, table, and column) in double quotes and any column values in single
quotes in your scripts. Object names that are also reserved words in SQL, or that contain special
characters (any character other than alphanumeric or _ ), must be surrounded by double quotes. If you
see the error message “Error parsing SQL. Check SQL input.”, you should check for object names without
double quotes in your script.
If you are working in a schema other than the default schema, object names must be fully qualified, as in
""."".
If your schema includes constraints to define relationships between tables (foreign key, or the
RELATIONSHIP syntax), it is recommended that your script first creates all the tables, and then at the end,
creates the relationships between them using the ADD CONSTRAINT syntax. This makes it easier to
troubleshoot the script and make changes.
If TQL is run using the flag --allow_unsafe, your statements will always execute without this warning.
Note that when running TQL from a script, you will need to decide what behavior you want if the script
contains changes that affect dependent objects. If you want the script to run even if objects with
dependencies are affected, run it using this flag, for example:
cat safest_script_ever.sql | tql --allow_unsafe
1. Open a new file in a text editor.
2. Type in the command to create the database, if it does not already exist:
CREATE database ;
3. Type in the command to specify the database to use:
USE database ;
4. Type in the command to create the schema, if you don’t want to use the default schema:
5. Type in each of the CREATE TABLE statements, with its column definitions, primary key
constraints, and sharding specification (if any).
6. At the end of your script, optionally type in the ALTER TABLE statements to add foreign keys to
use in joining the tables.
7. Save the file.
8. Run the script using one of these methods:
• Import a schema (use the SQL editor).
• Log in to the shell, copy your script to your ThoughtSpot instance using scp, and pipe
it to TQL:
$ cat create-schema.sql | tql

ThoughtSpot Administration Guide

Page 71

Schema creation examples

December 09, 2017

Schema cr
crea
eation
tion e
ex
xamples
Summary: Simple examples that illustrate how to use the TQL and the
ThoughtSpot Loader.
These examples demonstrate the steps involved in creating a schema using the ThoughtSpot SQL
Command Line (TQL). After the schema is created, you can load data into it with ThoughtSpot Loader.

Simple schema cr
crea
eation
tion e
ex
xample
The example creates a database (tpch) with two tables (customer, transaction). The example does not
create a schema explicitly. So it will use the default schema (falcon_default_schema).
In this example:
• The table customer has a primary key called customer_id. The table customer_transactions
has a primary key called transaction_id.
• The customer table is unsharded.
• The customer_transactions table is sharded into 96 shards using the transaction_id
column.
• Both tables have referential integrity on customer_id.
$tql
TQL> CREATE DATABASE tpch;
TQL> USE tpch;
TQL> CREATE TABLE customer (
name

VARCHAR(100),

address VARCHAR(255),
zipcode INT,
customer_id INT,
CONSTRAINT PRIMARY KEY (customer_id)
);
TQL> CREATE TABLE customer_transactions (
transaction_id INT,
customer_id INT,
amount DOUBLE,
transaction_date DATETIME,
CONSTRAINT PRIMARY KEY (transaction_id),

ThoughtSpot Administration Guide

Page 72

Schema creation examples

December 09, 2017

CONSTRAINT FOREIGN KEY (customer_id) REFERENCES
customer(customer_id)
)

PARTITION BY HASH (96) KEY (transaction_id);

Mor
More
ec
comple
omplex
x schema cr
crea
eation
tion e
ex
xample
The example uses a custom schema called sample_schema to hold the tables. Because of this, every table
reference has to be schema qualified.
$ tql
TQL> CREATE DATABASE "sample_db";
TQL> USE "sample_db";
TQL> CREATE SCHEMA "sample_schema";
TQL> CREATE TABLE "sample_schema"."customer" (
"c_custkey" BIGINT,
"c_name" VARCHAR(255),
"c_address" VARCHAR(255),
"c_city" VARCHAR(255),
"c_nation" VARCHAR(255),
"c_region" VARCHAR(255),
"c_phone" VARCHAR(255),
CONSTRAINT PRIMARY KEY ("c_custkey")
);
TQL> CREATE TABLE "sample_schema"."supplier" (
"s_suppkey" BIGINT,
"s_name" VARCHAR(255),
"s_address" VARCHAR(255),
"s_city" VARCHAR(255),
"s_nation" VARCHAR(255),
"s_region" VARCHAR(255),
"s_phone" VARCHAR(255),
CONSTRAINT PRIMARY KEY ("s_suppkey")
);
TQL> CREATE TABLE "sample_schema"."lineorder" (

ThoughtSpot Administration Guide

Page 73

Schema creation examples

December 09, 2017

"lo_orderkey" BIGINT,
"lo_linenumber" BIGINT,
"lo_custkey" BIGINT,
"lo_partkey" BIGINT,
"lo_suppkey" BIGINT,
"lo_orderdate" DATE,
"lo_orderpriority" VARCHAR(255),
"lo_shippriority" VARCHAR(255),
"lo_quantify" BIGINT,
"lo_extendprice" BIGINT,
"lo_ordtotalprice" BIGINT,
"lo_discount" BIGINT,
"lo_commitdate" DATE,
CONSTRAINT PRIMARY KEY ("lo_orderkey","lo_linenumber"),
CONSTRAINT FOREIGN KEY ("lo_custkey") REFERENCES "sample_schema"."customer"
("c_custkey"),
CONSTRAINT FOREIGN KEY ("lo_suppkey") REFERENCES "sample_schema"."supplier"
("s_suppkey")
)

PARTITION BY HASH (96) KEY (lo_orderkey);

ThoughtSpot Administration Guide

Page 74

Upload and run a SQL script

December 09, 2017

Upload and run a SQL script
Summary: Importing a schema through the Web browser makes it
possible to run your SQL script without needing to have a Linux login.
You can run a SQL script to create your database schema through the browser, without having to log in to
the shell on the ThoughtSpot instance. You can edit the script and run it directly in the browser to create
the schema. You can use this capability in any of these ways:
• Create the SQL script ahead of time, and use the browser to run it.
• Use the editor to type your SQL directly into the browser.
• Use the browser SQL interface as an interactive SQL editor, for example to test an existing script
or make changes to an existing schema.
1. Log into ThoughtSpot from a browser.
2. Click on DATA, on the top navigation bar.

3. Click Actions and select Upload schema
schema.

4. Drag and drop your SQL file into the browser, or choose Br
Bro
owse Y
Your
our Files to locate it.
5. You’re now in the SQL editor. Use it to view your script and make any changes.

ThoughtSpot Administration Guide

Page 75

Upload and run a SQL script

December 09, 2017

6. When ready, run your script by clicking the Ex
Execut
ecute
e button.
7. If there are any errors, correct them and run the script again.

ThoughtSpot Administration Guide

Page 76

How to change a schema

December 09, 2017

Ho
How
w tto
o change a schema
Summary: After you've created a schema and loaded data, you may
find yourself wishing you'd set things up a little differently. You can
make changes to the schema, such as changing the primary key,
relationships to other tables, and sharding.
Making changes to a schema after data has been loaded and users have created worksheets or pinboards
on the tables requires care, so that you don’t lose the relationship between the objects created in
ThoughtSpot and the underlying tables. If you follow the procedures here, your tables will retain their
relationships to the objects created on top of them.
 Tip: Always take a snapshot of your database before making any schema changes. This snapshot allows
you to revert back to the prior state if you make an error, or something doesn’t work as you expected after
the schema change.

Change the primary k
ke
ey ffor
or a table
Use this procedure to change the primary key for a table. But use it with caution, particularly if you are
changing to a primary key for which values are not unique.
You can change the primary key of a table without having to TRUNCATE it first and reload the data.
However, changing the primary key could result in data deletion. This is because of the upsert behavior
which is applied when multiple rows have the same primary key. This is very important to understand
ahead of time, if you are considering changing to a primary key for which values are not unique.
To change the primary key, first remove any existing primary key, and then define a new one (if any). You
do not need to truncate the tables to do this operation beginning in version 3.2. Any dependent objects
(pinboards or worksheets) will remain intact.
To change the primary key of a table:
1. Create a manual snapshot.
2. Connect to the database with the ThoughtSpot SQL Command Line (TQL).
3. Drop the existing primary key (if any), by issuing a command like this example:
TQL> ALTER TABLE "cart"
DROP CONSTRAINT
PRIMARY KEY;
Dropping a primary key can impact existing worksheets, answers, and pinboards. The system
warns you if dropping a primary key impacts other objects. To continue, use the -allow_unsafe flag.
4. Add a new primary key, if desired:
TQL> ALTER TABLE "cart"
ADD CONSTRAINT
PRIMARY KEY ("owner_id");
5. Test that any dependent objects (pinboards, worksheets, etc.) are still working correctly.
6. Delete the snapshot you created earlier using the command:

ThoughtSpot Administration Guide

Page 77

How to change a schema

December 09, 2017

tscli snapshot delete 

Change a rrela
elationship
tionship betw
between
een tables
Use this procedure to remove a relationship between tables or define a new one. This operation works for
both kinds of relationships: foreign key or generic relationship.
To change a relationship between two tables, first remove any existing relationship, and then define the
new relationship (if any). You do not need to truncate the tables to do this operation. Any dependent
objects (pinboards or worksheets) will remain intact.
To change the relationship between tables:
1. Create a manual snapshot.
2. Connect to the database with the ThoughtSpot SQL Command Line (TQL).
3. Issue the command to drop the existing relationship
Before dropping a relationship TQL checks for and then warns of any dependent objects. To
continue with the drop any way, use the --allow_unsafe flag. The following examples illustrate
several different types of drop operations.
Drop a foreign key by name, if it was given a name when it was defined:
TQL> ALTER TABLE
"sales_fact"
DROP CONSTRAINT
"FK_PO_number";
Drop a relationship by name, if it was given a name when it was defined:
TQL> ALTER TABLE "fruit_dim"
DROP RELATIONSHIP "REL_dates";
Drop the foreign key relationship explicitly, if it doesn’t have a name, by referencing the two
tables that are joined. This drops all foreign keys between the two tables:
TQL> ALTER TABLE "shipments"
DROP CONSTRAINT
FOREIGN KEY "orders";
Drop all generic relationships between two tables:
TQL> ALTER TABLE "wholesale_buys"
DROP RELATIONSHIP
WITH "retail_sales";
4. Define a new relationship, if you want to, using ALTER TABLE...ADD CONSTRAINT...
5. Test that any dependent objects (pinboards, worksheets, etc.) are still working correctly.
6. Delete the snapshot you created earlier using the command:
tscli snapshot delete 

ThoughtSpot Administration Guide

Page 78

How to change a schema

December 09, 2017

Change shar
sharding
ding on a table
You can change the sharding on a table or remove it altogether (creating a replicated table) using this
procedure. This procedure preserves the data within the table.
This procedure reshards a table. This is also called redistributing or repartitioning. You can use this method
to reshard a table without losing its data or metadata. This means that worksheets and pinboards built on
top of the table will continue to work.
You can use these steps to do any of these operations:
• shard a table that was previously replicated.
• change a replicated table to a sharded table.
• change the number of shards to use for a sharded table.
To change the sharding on a table:
1. Create a manual snapshot.
2. Connect to the database with the ThoughtSpot SQL Command Line (TQL).
3. Issue the command to change the sharding using this syntax:
TQL> ALTER TABLE 
[SET DIMENSION | SET FACT
[PARTITION BY HASH
[()]
[KEY()]]]
For example:
• To make a sharded table into a dimension table (replicated on every node), use:
ALTER TABLE "products"
SET DIMENSION;
• To make a dimension table into a sharded (fact) table or change the number of shards,
use:
ALTER TABLE "sales"
SET FACT PARTITION BY HASH (96)
KEY ("productID");
4. Test that any dependent objects (pinboards, worksheets, etc.) are still working correctly.
5. Delete the snapshot you created earlier using the command:
tscli snapshot delete 

ThoughtSpot Administration Guide

Page 79

Convert column data type

December 09, 2017

Con
onv
vert c
column
olumn da
data
ta type
Summary: You can convert the data in a column from one data type to
another by issuing a TQL command.
There are some details you should be aware of when doing a data type conversion.

Da
Data
ta type c
con
onv
version beha
behavior
vior
When converting from one data type to another, any values that can not be converted will be set to NULL.
If errors occur during data type conversion, the operation is aborted. However, you may choose to force
the conversion despite the errors. You can start TQL in allow_unsafe mode to continue with the data
conversion, at your own risk, of course! To start TQL in unsafe mode, issue this command:
tql --allow_unsafe
Multiple columns of a single table can be converted using a single TQL command. The behavior is
transactional. So for example, you would issue a command like this example:
ALTER TABLE products
MODIFY COLUMN product_id int,
MODIFY COLUMN supplier VARCHAR(4);
Also note that changing data type has implications on the primary key and sharding enforcement. For
example, changing the data type of a column that is part of the sharding key would lead to a redistribution
of data. Then imagine that the sharding key column contained the text values “00100”, “0100”, and “100”,
which all map to same integer value. If this type of a column is changed from a VARCHAR to an INT, then
it would be subject to the upsert behavior on primary keys. So, in this example, only one of the three rows
would be preserved.
Be aware that data type conversion will preserve the data in the underlying database table, but there is no
guarantee that any objects built on top of it (worksheets or pinboards) will be preserved. This is because
you might make a data type change that makes a chart built on top of the table invalid (for example a
growth chart would be invalidated if the date column it depends on were changed to a varchar column).

Support
Supported
ed da
data
ta type c
con
onv
versions
In general, the data type conversions that make logical sense are supported. But there are a few nuances
you should be aware of:
• When you convert from INT to BOOL, zero is converted to false, and all non-zero values are
converted to true.
• When you convert from BOOL to INT, true gets converted to 1, and false gets converted to 0.
• When you convert from DOUBLE to INT, the value gets rounded.
• When you convert from INT to DOUBLE, the value gets rounded.
• When you convert from DATETIME to DATE, the date part of value is preserved and the time
part is dropped.
• When you convert from DATE to DATETIME, the time gets added as 00:00:00. The date part of
the value is preserved.
• When you convert from DATETIME to TIME, the time part of the value is preserved.
• Conversion from TIME to DATETIME is not supported.

ThoughtSpot Administration Guide

Page 80

Convert column data type

December 09, 2017

Da
Datte and time c
con
onv
versions
Some data type conversion require a format string. These include:
• conversion from DATE/TIME/DATETIME
• conversion to DATE/TIME/DATETIME
For these types of conversions, you’ll use a special syntax using parsinghint and the date format
specifications supported in the strptime library function.
For the example, first create a table with a timestamp stored as a VARCHAR:
CREATE TABLE fruit_sales
(time_of_sale VARCHAR(32));
INSERT INTO fruit_sales
VALUES ('2015-12-29 13:52:39');
Now, convert the column from a VARCHAR to DATETIME, using the format %Y-%m-%d %H:%M:%S:
ALTER TABLE fruit_sales
MODIFY COLUMN time_of_sale DATETIME
[parsinghint="%Y-%m-%d %H:%M:%S"]
Finally, convert the column back to VARCHAR:
ALTER TABLE fruit_sales
MODIFY COLUMN time_of_sale VARCHAR(32);

Boolean tto
o sstring
tring c
con
onv
versions
Boolean to string conversions have format strings, too. You’ll use parsinghint as you do for date and
time conversions. You can choose among these approaches:
• Option 1: Specify string values for both true and false. Any non-matching values get converted
to null. In this example, “100” gets converted to true, and “0” gets converted to false. “-1” gets
converted to null.
ALTER TABLE db
MODIFY COLUMN s bool [parsinghint="100_0"];
• Option 2: Specify a string value for true. Any non-matching value gets converted to false. In this
example, “100” gets converted to true, “-1” and “0” get converted to false.
ALTER TABLE db
MODIFY COLUMN s bool [parsinghint="100_"];
• Option 3: Specify a string value for false. Any non-matching value get converted to true. In this
example, “-1” and “100” get converted to true, and “0” gets converted to false.

ThoughtSpot Administration Guide

Page 81

Convert column data type

December 09, 2017

ALTER TABLE db
MODIFY COLUMN s bool [parsinghint="_0"];

String tto
o boolean c
con
onv
versions
When converting from a string to a boolean, you must specify a string for true and false. By default, a
string to boolean conversion generates “true” for true, “false” for false.
ALTER TABLE db
MODIFY COLUMN b varchar(32);
But you may override the default strings that get generated by using parsinghint, as in this example:
ALTER TABLE db
MODIFY COLUMN b varchar(32) [parsinghint="tr_fa"];

Change the Da
Data
ta T
Type
ype of a C
Column
olumn
When you issue the TQL command to convert a column from one data type to another, the conversion is
handled automatically. However, you’ll need to ensure that any visualizations built on top of the table
display correctly.
You should always take a snapshot of your database before making any schema changes. This will allow
you to revert back to the prior state if you make an error, or something doesn’t work as you expected after
the schema change.
When changing a data type in an existing table, be aware that answers and pinboards created on top of
that table (or worksheets that include it) may change. This is because charts and aggregations depend
upon the data type. So for example changing from INTEGER to VARCHAR could break charts that used
the numeric data type INTEGER to calculate an average or a total. Because of this, use caution, and check
all dependent objects before and after changing the data type, to ensure that they display as intended.
To change the data type of a column:
1. Connect to the database with the ThoughtSpot SQL Command Line (TQL).
2. Issue the command to change the data type using this syntax:
TQL> ALTER TABLE 

MODIFY COLUMN  ;
For example:
ALTER TABLE fact100
MODIFY COLUMN product_id int;

ThoughtSpot Administration Guide

Page 82

Import CSV files with tsload

December 09, 2017

Import CS
CSV
V files with tsload
Summary: The tsload command is a common way to import data from
a CSV file.
Use ThoughtSpot Loader (tsload) to load data from a CSV text file into an existing table in ThoughtSpot.
ThoughtSpot Loader (tsload) is a common way to import data. When using tsload, you can load larger
datasets and make the loading process repeatable through scripting. The tsload command accepts flags
that enable you to specify column and row separators, date or timestamp formats, null value
representations, and similar parameters. Many of these options have defaults that you can override.
Before importing data, you need to Build the schema.
To use ThoughtSpot Loader, type the command tsload followed by the appropriate flags. You can see the
list of the flags it accepts in the ThoughtSpot Loader flag reference or by issuing tsload -help.
tsload supports both full and incremental data loads. For incremental loads, an upsert (insert or update) is
performed. If an incoming row has the same primary key as an existing row, it updates the existing row
with the new values.
You can integrate tsload into your ETL environment for more automated data loads. Most ETL tools
provide the ability to write target data into files and support scripted post-transformation actions that can
include loading data into ThoughtSpot. This procedure describes manually loading data, but the tsload
commands could be saved as a script:
1. Log in to the Linux shell using SSH.
2. Change to the directory where your CSV files are staged.
3. Invoke tsload, specifying the appropriate flags and your data source file:
$ tsload --target_database my_database
--target_table my_table --alsologtostderr
--empty_target --source_file my_file.csv --v 1
--field_separator "separator_char"
4. Repeat the data load for each of your CSV files.
This example imports the CSV file ssbm_customer.csv into the table CUSTOMER:
$ tsload --target_database SAMPLE_DB
--target_table CUSTOMER --alsologtostderr
--empty_target --source_file ssbm_customer.csv
--v 1 --field_separator "|"

ThoughtSpot Administration Guide

Page 83

Use a script to load data

December 09, 2017

Use a script tto
o load da
data
ta
Summary: Learn how to load one or files in bulk with a script.
If you need to load data from multiple CSV files, create a script to automate the process. You can also use
a similar script to automate recurring data feeds.

Unders
Understand
tand ho
how
w tto
o cr
crea
eatte a script
The data loading script is a text file that contains all the calls to tsload for loading the data from your
CSV files.
The example script shown here uses the cat command to read the data file, and pipes it to tsload. When
creating and testing your script, you may wish to replace each cat with cat -10, to load only the first ten
lines of each file. This allows you to quickly run a test of your script. When the test succeeds for all the
data files, you can then remove each -10, so the complete files will load when you run the script again.
1. Log in to the Linux shell using SSH.
2. Navigate to the directory that contains your CSV files and open a new file in a text editor.
3. Type in the commands to load the data. This example shows commands to load three files:
cat Players.csv | tsload
--target_database baseball --target_table "players"
--empty_target --field_separator ","
--max_ignored_rows 10 --bad_records_file bad_records.txt
--has_header_row --alsologtostderr --null_value ""
cat AllstarFull.csv | tsload
--target_database baseball --target_table "allstarfull"
--empty_target --field_separator ","
--max_ignored_rows 10 --bad_records_file bad_records.txt
--has_header_row --alsologtostderr --null_value ""
cat Appearances.csv | tsload
--target_database baseball --target_table "appearances"
--empty_target --field_separator ","
--max_ignored_rows 10 --bad_records_file bad_records.txt
--has_header_row --alsologtostderr --null_value ""
4. Save the file.
5. Run the script:
$ ./load_baseball_data.sh

Loading da
data
ta efficiently
If you have a very large data file that takes a long time to load, you can reduce the load time by splitting it
up into multiple files and loading them in parallel using multiple invocations of tsload. If the size of any of
your data files is greater than 50 million rows, running tsload in parallel can reduce the load time
significantly.

ThoughtSpot Administration Guide

Page 84

Use a script to load data

December 09, 2017

• Split up your large data file into multiple smaller files.
• Stage the data files in a location accessible to the node on which you’ll run the script. Usually
you’ll use an NAS mounted file system.
• Create a script to load the files (see example below).
• Run the script to load the files. You will make your script multi-threaded by invoking multiple
loader threads (between 1 and 5 are recommended).
To optimize the load time even further, determine what the bottleneck is and adjust your process
accordingly. If the disk I/O for reading the data files is the bottleneck, you can stage the data files on
separate NAS mounted file systems and reference them accordingly in your script. If the CPU on the
machine you’re using to run the load script is the bottleneck, you can split the load script into the same
number of parts as you have nodes in your ThoughtSpot instance, place one script on each node, and run
them in parallel. Make sure the other nodes are able to access the data files where they are staged.
Running the load script on separate nodes will put the data on all the nodes, just as when you run the
script on a single node. Running the script on all the nodes at the same time just lets you take advantage
of CPU power of each node for hashing data files.
For example, suppose you have 30 days of data in 30 files, one for the data collected on each day. Each
day’s data file contains 10 million rows, for a total of 300 million rows of data. You want to load the whole
month of data. For this example we’ll have 5 loader processes, each one handling 6 days of data. Here is a
sample script you could use the load the data files in parallel:
/* Script load_script.sh, loads 30 days of data in parallel */
#!/bin/bash
pidlist=""
cat day1.csv day2.csv day3.csv day4.csv day5.csv day6.csv | tsload
--target_database sales --target_table SALES_FACT --max_ignored_rows 10
--bad_records_file ./SALES_FACT.bad --date_format %Y-%m-%d
--date_time_format "%Y-%m-%d %H:%M:%S" --source_data_format delimited
--field_separator "|" --null_value "" --enclosing_character "\""
--boolean_representation 1_0 &
pidlist="$pidlist $!" &
cat day7.csv day8.csv day9.csv day10.csv day11.csv day12.csv | tsload
--target_database sales --target_table SALES_FACT --max_ignored_rows 10
--bad_records_file ./SALES_FACT.bad --date_format %Y-%m-%d
--date_time_format "%Y-%m-%d %H:%M:%S" --source_data_format delimited
--field_separator "|" --null_value "" --enclosing_character "\""
--boolean_representation 1_0 &
pidlist="$pidlist $!" &
cat day13.csv day14.csv day15.csv day16.csv day17.csv day18.csv | tsload
--target_database sales --target_table SALES_FACT --max_ignored_rows 10
--bad_records_file ./SALES_FACT.bad --date_format %Y-%m-%d
--date_time_format "%Y-%m-%d %H:%M:%S" --source_data_format delimited
--field_separator "|" --null_value "" --enclosing_character "\""
--boolean_representation 1_0 &
pidlist="$pidlist $!" &
cat day19.csv day20.csv day21.csv day22.csv day23.csv day24.csv | tsload
--target_database sales --target_table SALES_FACT --max_ignored_rows 10
--bad_records_file ./SALES_FACT.bad --date_format %Y-%m-%d
--date_time_format "%Y-%m-%d %H:%M:%S" --source_data_format delimited
--field_separator "|" --null_value "" --enclosing_character "\""
--boolean_representation 1_0 &
pidlist="$pidlist $!" &

ThoughtSpot Administration Guide

Page 85

Use a script to load data

December 09, 2017

cat day25.csv day26.csv day27.csv day28.csv day29.csv day30.csv | tsload
--target_database sales --target_table SALES_FACT --max_ignored_rows 10
--bad_records_file ./SALES_FACT.bad --date_format %Y-%m-%d
--date_time_format "%Y-%m-%d %H:%M:%S" --source_data_format delimited
--field_separator "|" --null_value "" --enclosing_character "\""
--boolean_representation 1_0 &
pidlist="$pidlist $!" &
wait $pidlist
Call your script using a command like:
nohup bash ./load_script.sh > master_log.txt &
tail -f master_log.txt
Constructing your script in this way will execute all the commands in the background, and output to the
file master_log.txt. You’ll see a running status as the commands in the script execute. After the script
completes, you can check the log file for detailed information, such as the number of rows that loaded
successfully.

ThoughtSpot Administration Guide

Page 86

Delete a data source

December 09, 2017

Delet
Delete
e a da
data
ta sour
sourc
ce
Summary: How to prepare for and delete a data source using the
ThoughtSpot application.
There are two separate ways to delete a data source, through the browser or through TQL describes the
dependency checking that occurs when deleting or changing a table using TQL. When you want to delete
a data source, you first need to handle any dependent objects that have been built on top of it. You can
easily see these dependencies, and choose how to handle them before deleting the data source.

Check da
data
ta sour
sourc
ce dependencies
You can see all of the dependencies for any data source (worksheet or table) on the DATA page.
To view dependent objects for a data source:
1. Click on DATA, on the top navigation bar.

2. Click the name of the data source whose dependencies you want to view.
3. Click Dependents
Dependents.
You will see a list of the names of the dependent objects (worksheets and pinboards), and the
columns they use from that data source. You can use this information to determine the impact
of changing the structure of the data source or to see how widely it is used.

4. Click on a dependent object to modify or delete it.
If you want to remove the dependency by modifying the dependent object, you’ll need to
remove all search terms or columns that refer back to the data source you are trying to delete.
5. When all dependencies have been removed, you will be able to go back and delete the data
source.

ThoughtSpot Administration Guide

Page 87

Delete a data source

December 09, 2017

Delet
Delete
e a da
data
ta sour
sourc
ce
You can delete data sources from the browser, as long as they were not created by an administrator
through tsload or Data Connect.
You can delete data sources from the browser if they were created from the browser. These types of data
sources include:
• Data imported from the browser.
• Worksheets.
ThoughtSpot checks for dependencies whenever you try to delete a table or worksheet.
1. Click on DATA, on the top navigation bar.

2. Check the box next to the name of the data source you want to delete.
3. Click the delete icon.

4. If you attempt to delete a data source with dependent objects, the operation will be blocked.
You will see a list of dependent objects with links.

ThoughtSpot Administration Guide

Page 88

Delete a data source

December 09, 2017

5. Click on a dependent object to modify or delete it.
If you want to remove the dependency by modifying the dependent object, you’ll need to
remove all search terms or columns that refer back to the data source you are trying to delete.
6. When all dependencies have been removed, you will be able to go back and delete the data
source.

ThoughtSpot Administration Guide

Page 89

Delete or change a table in TQL

December 09, 2017

Delet
Delete
e or change a table in T
TQL
QL
Summary: You can delete a data source in the web browser or using
ThoughtSpot SQL Command Line (TQL).
When you enter a TQL statement, the system warns you of possible dependency consequences with a
prompt asking if you’d like to proceed. This should make you feel safe issuing TQL commands, even
commands like dropping a table.
If TQL is run using the flag --allow_unsafe, your statements will always execute without this warning.
Note that when running TQL from a script, you will need to decide what behavior you want if the script
contains changes that affect dependent objects. If you want the script to run even if objects with
dependencies are affected, run it using this flag, for example:
cat safest_script_ever.sql | tql --allow_unsafe
If you do not run the script using the flag, it will fail if any of its commands might cause problems with
dependent objects.
TQL actions with possible dependency consequences include:
• Change, add, or remove a primary key.
◦ When changing or adding a primary key, if the key in question is not unique in the data
it may cause deletion of rows, because of upserts occurring when duplicate primary
keys are found.
◦ When changing or removing a primary key, incoming foreign key relationships will be
broken.
• Change a column datatype.
• Add a relationship or foreign key.
• Drop a relationship or foreign key constraint.
• Change or add a sharding key.
• Drop a table, schema, or database.
When issuing one of the above commands, you will see a warning message similar to this:
TQL> ALTER TABLE table1
DROP CONSTRAINT PRIMARY KEY;
WARNING: This operation will break the Foreign Key relationship “products”
with table “sales”, which will break 34 user-visible visualizations and
2 Worksheets. We recommend taking a snapshot before performing this operation.
Do you wish to proceed? (yes/no).

ThoughtSpot Administration Guide

Page 90

About data modeling

December 09, 2017

About da
data
ta modeling
Summary: Modeling, tagging, and adding links between your data
sources can make the data even easier to search.
Data modeling allows you to define metadata and other aspects of your data. For example, you can give
data columns search friendly names or predefine how they can be explored and aggregated. Metadata
include such information as Column Names
Names, Column V
Visibility
isibility, Column and Da
Data
ta Definition
Definition, Column Rank
and so forth.
When you load data, ThoughtSpot has defaults for data modeling metadata. After loading data, you can
start searching your data without doing any data modeling, creating relationships, or tagging. However,
since you know your data best, you can customize the modeling settings. Putting some thought into these
will make the data even easier and more intuitive to search for your end users.

User int
interf
erfac
aces
es ffor
or modeling da
data
ta
Data modeling is a very lightweight process compared to what you may have experienced in other tools.
You can configure the model for an individual data table or you can view and configure all the system data
using a modeling file. Editing the data model file requires that you have administrative privileges.
The model file contains a row for each column in your data set. It isn’t unusual to have tens of thousand of
rows in this file. This means editing this file is equivalent to editing all the tables at once. When you add
new data to your system, this file expands to accommodate the new data columns you have added.
Both of these methods, have the same effect, they improve search. Moreover, while they have different
effects of scale, they use the same mechanisms to accomplish these effects.

Modeling ttopics
opics
The following topics explain how to model your data:
• Change a table’
table’ss da
data
ta model
Explains how to make modeling settings for a table you’ve just loaded, or to make a quick
change to existing settings.
• Edit the ssy
ystem-wide da
data
ta model
Explains how to define a default data model to use for data system-wide.
• Da
Data
ta modeling settings
Explains the possible data model settings and their accepted values. These are the same for a
table or the system.
• Link tables using rrela
elationships
tionships
Linked tables can be searched together or combined into a worksheet for easy searching. Tables
that have no relationship between their columns can not be combined in a single search.
• About sstick
tickers
ers
You can create stickers to make it easier for people to find data sources and pinboards.

ThoughtSpot Administration Guide

Page 91

Change a table's data model

December 09, 2017

Change a table's da
data
ta model
Summary: You can adjust the data model for a newly loaded table.
To make modeling settings for a table you’ve just loaded, or to make a quick change to existing settings,
use the ThoughtSpot web interface. You can adjust the Columns settings from the data management
listing.
You can change all the same data model settings here as in the model file. This method is easier and faster,
unless you need to make many settings in bulk. In that case, using the model file is recommended.
1. Click on the DATA icon, to get to the data management listing.
2. Click on a data source you own or can edit.

This brings up the Columns screen, where you’ll make your modeling settings.
3. Modify one or more column settings.
Descriptions of the possible settings are listed in Data modeling settings.
4. Save your changes.

5. To check your changes, use the SEARCH page to search for across the changed data.

ThoughtSpot Administration Guide

Page 92

Change a table's data model

December 09, 2017

Rela
elatted inf
informa
ormation
tion
• Data modeling settings
• Edit the system-wide data model

ThoughtSpot Administration Guide

Page 93

Edit the system-wide data model

December 09, 2017

Edit the ssy
ystem-wide da
data
ta model
Summary: Edit the modeling file to edit your data settings.
When you load data, ThoughtSpot uses defaults for data modeling metadata. You change these defaults
using the data modeling file if you have access to the ADMIN > Da
Data
ta Management page. This means
editing this file allows you to navigate and edit all your system’s data columns at once, in bulk. When you
(or your users) add new data to your system, this file changes as it expands to accommodate new data
columns.
 Tip: If you just want to change a subset of your data, use the Change a table’s data model instead.

Ov
Overvie
erview
w of the modeling pr
proc
oces
esss
The data formats you use in your system are controlled by the modeling file, an Excel file. To make these
changes you download the model file, change the model, and upload your changes back into the system.
In each row of the modeling file, all the data properties corresponding to a column from your data are
listed. You can modify many of these properties by typing in the new value. Remember these important
guidelines when editing the model file:
• Do not modify any value in a column which contains DoNotModify in the field under the column
heading.
• Make sure to keep the file in the same format as it had when you downloaded it.
The model file contains a row for each column in your data set. It isn’t unusual to have tens of thousand of
rows in this file. You can change all or a subset of rows. You can edit the file to leave the heading rows and
only those rows you want to change. This can make the file more convenient to work with.
The model file must be saved as UTF-8 encoded. If your model file includes multi-byte characters, make
sure you save it in the correct format or you won’t be able to upload it after making your changes.

Do
Download
wnload the model file
Before you can make changes to the model file, you need to download it. Then, you edit it using Microsoft
Excel, vi/vim, or a similar text editing tool.
To obtain the model file:
1. Log in to ThoughtSpot from a browser as an Administrator user.
2. Click on the admin tab in the top navigation bar.

3. Click on Da
Data
ta Management
Management.
4. Click Do
Download
wnload model.xls
model.xls.

ThoughtSpot Administration Guide

Page 94

Edit the system-wide data model

December 09, 2017

Edit the file and change the settings
You’ll make changes to the settings using this procedure. To see a list of the changes you can make, see
Data modeling settings. You can edit any of the values in the model file, except for those where the words
DoNotModify appear below the column header. To make changes in the model file:
1. Open the model file you downloaded (model.xls) in Excel, vi/vim, or a text editor.
If you are using Excel, you may see a warning message.
![](/images/warning_open_model_excel.png)
Click YES to proceed.
2. Find the column you want to modify.
Descriptions of the meanings of the columns are listed in Data modeling settings.
3. Select the value you want to change.
4. Type in the new value.
5. After making all your changes, save the model file.
If you are using Excel, you will see a message. Click YES to save the file.

The model file must be saved as UTF-8 encoded. If your model file includes multi-byte
characters, edit the file using vi or vim to ensure the file is saved in the correct format.

ThoughtSpot Administration Guide

Page 95

Edit the system-wide data model

December 09, 2017

Otherwise, you won’t be able to upload it after making your edits.

Upload the edit
edited
ed file
After you have made changes to the modeling file, you must upload it back to ThoughtSpot before the
changes will take effect. To upload the model file:
1. Log in to ThoughtSpot from a browser as an Administrator user.
2. Click on the Admin icon, on the top navigation bar.

3. Click on Da
Data
ta Management
Management.
4. Click Br
Bro
owse y
your
our files to upload the model.xls file, or drag and drop it in the zone.

If you receive an error message upon uploading the file, check that it does not include any multibyte characters (for example, Japanese or other multi-byte language characters). If it does,
you’ll need to download the file again and make your edits using vi or vim.
If you choose to remove all the rows you have not changed from the model file before uploading
it. If you upload a model file that includes only the changed rows, you won’t lose any of the preexisting model file settings. This is a good option if your model file is causing an error on upload,
but you aren’t sure where in the model file the problem is.
As soon as the file is uploaded, ThoughtSpot performs any necessary re-indexing for you automatically.
Your new settings will be reflected within a few minutes.

Rela
elatted inf
informa
ormation
tion
• Data modeling settings
• Change a table’s data model

ThoughtSpot Administration Guide

Page 96

Overview of data modeling settings

December 09, 2017

Ov
Overvie
erview
w of da
data
ta modeling settings
You can change these settings in two ways, both of which have change the model. If you want to make a
few small changes, you should make them in the ThoughtSpot application if you want to make many
changes you should edit the modelling file. Whether you are changing data modeling settings using the
modeling file or the Web interface, the settings and their accepted values are the same.

Modeling settings
This index lists the editable data modeling settings:
Setting
name

Description

Can be modeled
in a W
Worksheet
orksheet

Column
Name

Sets the name of the column to be used in searches.

Yes

Description

Adds a text description of what the column contains.

Yes

Data Type

Read only. Shows the column’s data type.

Column
Type

Sets the type of column, either ATTRIBUTE or MEASURE.

Additive

Controls the type of aggregations that will be available for a column.

Aggregation

Sets the default aggregation type for a column.

Hidden

Sets the visibility of a column.

Synonyms

Adds synonyms that can be used in the search bar to refer to a
column.

Index Type

Sets the type of index that will be created for a column.

Geo Type

Enables a column to be used in GeoMap visualizations.

Priority

Changes the priority of a column in search suggestions.

Number
Format

Specifies the format to use when showing a numeric value in the
column.

Date Format

Specifies the format to use when showing the dates in a column.

Currency
Format

Specifies the format to use when showing the currencies in a column.

ThoughtSpot Administration Guide

Yes

Page 97

Overview of data modeling settings

Setting
name

Description

Attribution
Dimension

Only applies to tables that join over a Chasm Trap. Designates
whether the tables depend on this column for attribution.

December 09, 2017

Can be modeled
in a W
Worksheet
orksheet

Da
Data
ta modeling ffor
or w
worksheets
orksheets
For worksheets, only some of the settings can be modified, whether you are using the modeling file or the
Web interface. The editable settings for worksheets are:
• Name
• Description
• Synonyms
If you want to change any of the settings that cannot be modified in a worksheet, you need to make your
changes to the underlying table instead, and they will be reflected in all worksheets that use the table.

Rela
elatted inf
informa
ormation
tion
• Model the data for searching
• Add a geographical data setting for a column
• Set the search suggestions priority for a column

ThoughtSpot Administration Guide

Page 98

Set column name, description, and type

December 09, 2017

Set c
column
olumn name
name,, description, and type
Summary: Modeling includes setting basic information for a data
column such as its name, description, and type.
Basic information for a data column is its NAME
NAME, DESCRIPTION
DESCRIPTION, and TYPE
TYPE. All of these can influence how
a user experiences your data. For example, the DESCRIPTION appears as a “tip” when a user hovers over a
column. So it is the means for helping users understand where the data comes from.

Change the c
column
olumn name
Column Name (UI)/C
ColumnName (model file) is the name that displayed to users for that column in
ThoughtSpot. The column name is what users type to add that column to their search. Change the text
that is shown for the column names in ThoughtSpot to make the names more meaningful to users.
The model file contains a row for each column in your data set. It isn’t unusual to have tens of thousand of
rows in this file. You can change all or a subset of rows. You can edit the file to leave the heading rows and
only those rows you want to change. This can make the file more convenient to work with.
The default is the name you gave the column when you defined the table in the database or imported the
CSV file from the browser.
1. Find the column name you want to change.
2. Type in the new column name.
3. Save your changes.

Change c
column
olumn description
Description (UI)/C
ColumnDescription (model file) an optional description for the corresponding column.
You can provide a description for a specific column, to provide additional information for users about the
data it contains. When a user hovers over the column, a tooltip will show this description.
To create a column description:
1.
2.
3.
4.

Find the column description you want to change.
Enter a new description.
Repeat for all columns where you want to add a description.
Save your changes.

Change c
column
olumn type
Column T
Type
ype (UI)/C
ColumnT
olumnType
ype (model file) describes the kind of data a column stores. This is set
automatically upon defining the table, but in some cases, you may want to change the type. There are two
types of columns:
• ATTRIBUTE contains a property, like name, address, or id number.
• MEASURE contains a numeric value that can be compared in a meaningful way using math, such
as a count or measurement.
When a new table is created, the default column type is set according to the Da
Data
ta T
Type
ype (UI)/Da
DataT
taType
ype
(model file) defined for each column. By default, columns with the numeric data types (FLOAT, DOUBLE,
INT, or BIGINT) are assigned the type MEASURE. Columns with VARCHAR, BOOL, or date/time data types are
assigned the type ATTRIBUTE.

ThoughtSpot Administration Guide

Page 99

Set column name, description, and type

December 09, 2017

Usually the default setting for column type works fine. But occasionally you’ll need to change a MEASURE
to an ATTRIBUTE. Examples of numeric values for which mathematical operations are not meaningful
include:
•
•
•
•
•

ID numbers
Key values that are primarily used for joining tables
Product number or SKU
Sports team member jersey number
Year, when separate from a date (e.g. 1999, 2000)

To change the column type:
1. Find the column type you want to change.
2. Change it to either MEASURE or ATTRIBUTE.
3. Save your changes.

Rela
elatted inf
informa
ormation
tion
• Model the data for searching
• Hide column or define a column synonym

ThoughtSpot Administration Guide

Page 100

Set ADDITIVE or AGGREGATION

December 09, 2017

Set ADDITIVE or A
AGGREGA
GGREGATION
TION
Summary: You can allow aggregate on MEASURE columns and some
ATTRIBUTE columns.
Aggregation is grouping many units or parts into a new value. In data, aggregation gathers multiple input
values and calculates an summary value from them. You then use this aggregated value to do an analysis.
Every summary value results from a data aggregation function. An example aggregation function would
be average or minimum. You can control how aggregation works in your data.

Making an A
ATTRIBUTE
TTRIBUTE c
column
olumn ADDITIVE
Your data may contain a column with a numeric data type that you have defined as an ATTRIBUTE rather
than a MEASURE. For example, you may have ATTRIBUTE column with an INTEGER data type that represents
age. Typically, these columns have an ADDITIVE setting of NO. Within a search result that contains data
from this column, the options for each column on the left side of the screen includes:
• UNIQUE C
COUNT
OUNT OF
• TOTAL C
COUNT
OUNT OF

To display extended aggregate view options, you must set ADDITIVE to YES on these ATTRIBUTE columns.
This option is only possible on columns that have a numeric data type (FLOAT, DOUBLE or INTEGER) or a
date data type (DATE, DATETIME, TIMESTAMP, or TIME). After you make this change, these additional view
options area-charts offered:
•
•
•
•
•
•
•
•

TOTAL OF
AVG OF
STD DEVIA
DEVIATION
TION OF
VARIANCE OF
TOTAL C
COUNT
OUNT OF
UNIQUE C
COUNT
OUNT OF
MIN OF
MAX OF

ThoughtSpot Administration Guide

Page 101

Set ADDITIVE or AGGREGATION

December 09, 2017

To change this setting:
1. Find the column whose ADDITIVE setting you want to change
2. Select the ADDITIVE toggle.
3. Change the value to one of these:
• YES or NO, if using the Web interface.
• TRUE or FALSE, if using the model file.
4. Save your changes.

Change A
Aggr
ggrega
egation
tion
Both MEASURE columns and ATTRIBUTE columns support AGGREGA
GGREGATION
TION operations. To aggregate a
column without having to enter the aggregation type explicitly in your searches every time, you can set a
default Aggr
ggrega
egation
tion for that column. Setting this default can make combining data more intuitive and
faster.
ATTRIBUTE columns have AGGREGA
GGREGATION
TION(UI)/A
Aggr
ggrega
egationT
tionType
ype (model file) values with default aggregate
type of NONE
NONE. You can change AGGREGA
GGREGATION
TION to one of the supported aggregation types. To extend the
available aggregation actions, set ADDITIVE on these columns to YES (TRUE).
Aggr
ggrega
egatte type

Description

NONE

Does no aggregation. This is the default for ATTRIBUTE type columns.

SUM

Adds the values together and returns the total. This is the default for MEASURE
type columns.

AVERA
VERAGE
GE

Calculates the average of all the values.

MIN

Calculates the minimum value.

MAX

Calculates the maximum value.

STD_DEVIA
TD_DEVIATION
TION

Calculates the standard deviation of all the values.

ThoughtSpot Administration Guide

Page 102

Set ADDITIVE or AGGREGATION

Aggr
ggrega
egatte type

Description

VARIANCE

Calculates the variance of all the values.

COUNT

Calculates the total number of values.

COUNT_DIS
OUNT_DISTINCT
TINCT

Calculates the total number of distinct values.

December 09, 2017

Keep in mind that not all MEASURE data should be aggregated. Consider a table containing data about
athletes on a sports team. The data contains some numerical values, including points scored, salaries, and
jersey numbers for each of the players. Because jersey number is an INTEGER, it would become a column
of type MEASURE (not ATTRIBUTE). So it will aggregate, by default. But you may want to make its
aggregation type NONE instead. This ensures that search results that include jersey number will not
attempt to compare or aggregate those values in a way that is not meaningful.
To set this value.
1.
2.
3.
4.

Find the column whose default aggregation type you want to change
Select its Aggr
ggrega
egation
tion. If using the modeling file, use the Aggr
ggrega
egationT
tionType
ype setting.
Select the new default aggregation type.
Save your changes.

Rela
elatted inf
informa
ormation
tion
Model the data for searching

ThoughtSpot Administration Guide

Page 103

Hide a column or define a synonym

December 09, 2017

Hide a c
column
olumn or define a ssynon
ynonym
ym
Summary: Hide a column from users or make it easier to find by
assigning a synonym.
You can hide columns from users in ThoughtSpot without dropping them from the database. It is common
to hide a column when its data contains identifier columns that are used to join tables, but which do not
have any meaning to users.
Alternatively, rather than hiding a column, you can make it easier to find by creating synonyms for it. This
is helpful, for example, when different departments refer to the data using different terminology.

Hide a c
column
olumn
As the number of columns in the dataset increases, the search experience requires more effort. Users have
to navigate through larger numbers of columns to choose the correct one. There might also be some
columns in the dataset that you don’t want to expose to the users.
Change the HIDDEN (UI)/Hide
Hide (model file) setting to hide a column. By default, all columns in a data
source ware shown in ThoughtSpot. To hide these columns, set the HIDDEN setting to YES.
1. Find the HIDDEN (UI)/Hide
Hide (model file) setting for a column.
2. Set its value to YES.
3. Save your changes.

Cr
Crea
eatte ssynon
ynonyms
yms ffor
or a c
column
olumn
When users search a data source, they might try typing different words to try to retrieve a particular
column. This could be due to different groups in your organization using different terms for the same data.
Or maybe your users just intuitively use different words when searching for that item. Using synonyms
allows them to access the data even if the term they choose isn’t the same as the actual column name.
You can set column synonyms for columns in tables, user imported data, and worksheets. The returned
table or chart uses the actual column name, but the search bar reflects the term the user typed in (the
synonym).
To create a column description:
1. Find the column for which you want to add synonyms.
2. Select its Synon
ynonyms
yms.
3. Type in a comma separated list of the synonyms you want to add.
If a synonym is more than one word, it must be enclosed in double quotes. If you are using the
Web interface, you would type:
profit,"gross profit"
If you are using the model file, the list of synonyms must be enclosed in square brackets. For
example:
[profit, "gross profit"]

ThoughtSpot Administration Guide

Page 104

Hide a column or define a synonym

December 09, 2017

4. Save your changes.

Rela
elatted inf
informa
ormation
tion
Model the data for searching

ThoughtSpot Administration Guide

Page 105

Change the index type

December 09, 2017

Change the inde
index
x type
Summary: ThoughtSpot indexes column names and unique column
values. The indexes are used to dynamically generate suggestions in
the search bar when typing a search.
A column’s index influences the suggestions that appear for that column in search. You can modify a
specific column’s INDEX TYPE in the DATA > T
Tables
ables > C
Columns
olumns page or to set a system-wide Inde
Index
x value
in the modeling file.
 Warning: If a column has a very large free text values, ThoughtSpot does not recommended to
changing the column indexing. These should not to be indexed, because indexing on these values is not
useful and may generate confusing suggestions.

Def
Default
ault inde
indexing
xing
The default behavior of indexing is as follows:
•
•
•
•

All column names are indexed using their ColumnName value.
Values for columns with the column type of MEASURE are not indexed.
Values for columns with the data type of DATE are not indexed.
Columns that contain a large amount of free-form text (i.e. the number of characters in more
than a few of the fields is more than 50) are indexed as PREFIX_ONLY by default.
• Short strings (like a firstname column) are indexed using PREFIX_AND_SUBSTRING by default,
which indexes both prefix and substrings.
You can override the default behavior by editing the modeling file to change the Inde
Index
x value for any
columns that should be indexed differently. There are several different supported index types:
Inde
Index
x type

Description

DEFAULT

This is the default value. The default indexing behavior will apply to
the column values, depending on their type. PREFIX_AND_SUBSTRING
for short values and PREFIX_ONLY for long values and free-form text.

DONT_INDEX

Prevents indexing on the column values.

PREFIX_AND_SUBSTRING

Allows full indexing such that prefix and sub-string search both work
for the column values.

PREFIX_ONLY

Allows indexing such that only prefix search works for the column
values.

PREFIX_AND_WORD_SUBSTRING

Allows indexing such that only prefix search works for each word of
a multi-word string, for the column values.

Mak
Make
e a change
1. Find the column whose index type you want to modify
2. Set its Inde
Index
xT
Type
ype.

ThoughtSpot Administration Guide

Page 106

Change the index type

December 09, 2017

If you are using the model file, double click in the Inde
Index
x cell, and type in the index type you want
to use. Consider a column in which there are four values ‘ThoughtSpot’, ‘Thought’, ‘Spot’ and
‘Thought Spot’. If you search for ‘sp’, depending on the setting for indexing, the column value
search result suggestions will vary:
Inde
Index
x field v
value
alue

Sear
Search
ch bar sugges
suggestions
tions

DEFAULT

‘ThoughtSpot’, ‘Spot’ and ‘Thought Spot’

DONT_INDEX

No suggestions.

PREFIX_AND_SUBSTRING

‘ThoughtSpot’, ‘Spot’ and ‘Thought Spot’

PREFIX_ONLY

‘Spot’

PREFIX_AND_WORD_SUBSTRING

‘Spot’ and ‘Thought Spot’

3. Save your changes.

Rela
elatted inf
informa
ormation
tion
Model the data for searching

ThoughtSpot Administration Guide

Page 107

Add a geographical data setting

December 09, 2017

Add a geogr
geographical
aphical da
data
ta setting
Certain attribute columns that contain location data can be used to create GeoMaps. ThoughtSpot
supports Latitude, Longitude, Zip Code, US States, US Counties, Countries, and select international subnation regions.
You can designate a column as Geo by editing the GEO C
CONFIG
ONFIG column in the table Columns page. You
cannot edit the geo configuration column information in the model.xls file.

Guidelines ffor
or geogr
geographic
aphic c
columns
olumns
Columns that can be designated as Geo columns need to contain text (VARCHAR) data unless they contain
latitude/longitude data. Latitude and longitude columns can contain numeric data (DOUBLE) or text.
If you are using a column with the data type DOUBLE for latitude and longitude, you will also need to
change the following settings for those columns:
• set Column T
Type
ype to ATTRIBUTE
• set Additiv
dditive
e to NO
• set Aggr
ggrega
egation
tion T
Type
ype to NONE
For information these settings, see Set ADDITIVE or AGGREGATION.

Ho
How
w tto
o edit geogr
geographic
aphic c
columns
olumns
1. Find the GEO C
CONFIG
ONFIG for the column that contains the geographical data.
2. Select the column to display the Specify Geogr
Geographic
aphic C
Configur
onfigura
ation dialog.

3. Change the value to the appropriate GEO C
CONFIG
ONFIG, depending on the kind of geo data the
column contains.
If your data includes latitude and/or longitude columns that are stored as a numeric data type
(DOUBLE), make these changes for those columns:

ThoughtSpot Administration Guide

Page 108

Add a geographical data setting

December 09, 2017

a. Change the Type to ATTRIBUTE.
b. Change ADDITIVE to NO/FALSE.
4. Save your changes.

Lis
Listt of geotypes
  
 ## Related information [Model the data for searching](semanticmodeling.html#)
GeoT
GeoType
ype

Description

COUNTRY_REGION

Countries

Type: Ex
Example
ample

• name: United States
• long name: United States
• name_sort: United States of
America
• abbreviation: U.S.A.
• adm0_a3: USA
• adm0_a3_is: USA
• adm0_a3_us: USA
• admin: United States of
America
• brk_a3: USA
• brk_name: United States
• formal_en: United States of
America
• iso_a2: US
• iso_a3: USA
• iso_n3: 840

COUNTY

Counties in the United States
• santa clara county
• pike county, ohio
• pike county, OH

STATE_PROVINCE

States in the United States
• name: California
• US Postal Service abbreviation: CA

LATITUDE

Must be used with LONGITUDE
• 37.421023
• 1.282911

LONGITUDE

Must be used with LATITUDE
• −122.142103
• 103.848865

ZIP_CODE

Zip codes and zip codes +4 in the United States

ThoughtSpot Administration Guide

• po_name: MT MEADOWS
AREA

Page 109

Add a geographical data setting

GeoT
GeoType
ype

Description

December 09, 2017

Type: Ex
Example
ample

• ZIP: "00012"
• zip2: 12

Other Sub-nation
Regions

Administrative regions found in countries other than the United States

ThoughtSpot Administration Guide

• bremen
• normandy
• west midlands

Page 110

Set the search suggestions priority

December 09, 2017

Set the sear
search
ch sugges
suggestions
tions priority
Summary: You can change the priority that determines which columns
are shown in search suggestions and the order in which they appear.
A column’s INDEX PRIORITY determines the order or rank in which it and its values appear in the search
dropdown.

By default, the INDEX PRIORITY value is set to “1” for all columns. You can push a column up in the order
(increase the rank) by increasing its INDEX PRIORITY value. A higher value (like 2) will cause the
corresponding column and its values to appear higher up in the search dropdown than columns with
lower value (like 1).

ThoughtSpot Administration Guide

Page 111

Set the search suggestions priority

December 09, 2017

You should only use numbers between 1-10 in the INDEX PRIORITY field. These values impact the usage
based rankings (UBR).
1. Change the value to a number between 1 and 10. Use a value between 8-10 for important
columns to improve their search ranking. Use 1-3 for low priority columns.
2. Save your changes.

Rela
elatted inf
informa
ormation
tion
Model the data for searching

ThoughtSpot Administration Guide

Page 112

Set number, date, and currency formats

December 09, 2017

Set number
number,, da
datte, and curr
currenc
ency
y fforma
ormats
ts
Summary: Explains how to set key formats for column values.
You can set number, date, and currency display formats. These formats define how these value types
display in tables and charts.

Number fforma
ormats
ts
You can set a format for how numbers are displayed in tables and charts. For example, you can display
numbers with a different number of digits after the decimal point, based on the data modeling setting
Forma
ormatt P
Pa
att
ttern
ern. You can use any of the supported number formats for delimiters and number of digits to
show using Java Decimal Notation. Currency symbols are not supported.
The system has default values which are:
• #,### for integer data types (INT, BIGINT).
• #,###.00 for decimal data types (DOUBLE and FLOAT).
These are some examples of formats you can use:
Stor
ored
ed V
Value
alue

Forma
ormatt P
Pa
att
ttern
ern

Displa
Display
yV
Value
alue

12345.6789

#,##0.##

12,345.68

12345.6789

#,##0.###

12,345.679

12345.6789

#,##0.00000

12,345.68

12345.6789

#,##0

12,345

12345.6789

#,##0.00

12,345.68

12345

#,##0.##

12,345

12345

#,##0.00

12,345.00

You can change the date format used to display a column’s values for a single table or, by editing the data
model, for the entire ThoughtSpot instance. Editing the data model file requires that you have
administrative privileges.
1. Decide if the change is for a table or the entire instance.
2. Find the Forma
ormatt P
Pa
att
ttern
ern for the column. This is either a column in a single table or a column in
the data modeling file.
3. In the column, enter the format you want to use.
4. Save your changes. If you are using a data-modeling file you’ll need to upload the new file to
your installation.

ThoughtSpot Administration Guide

Page 113

Set number, date, and currency formats

December 09, 2017

Profile-based number formatting
Number formatting is set by default based on your ThoughtSpot profile’s Pr
Pref
eferr
erred
ed locale setting. You can
set this value to accommodate your geographic locations.

For example, if you are using ThoughtSpot in the US, the number formatting should look like this:
xxx,xxx.xx. And in Europe, it should look like this: xxx.xxx,xx.

Da
Datte fforma
ormats
ts
Forma
ormatt P
Pa
att
ttern
ern (UI)/ Forma
ormatt P
Pa
att
ttern
ern (model file) formats for how dates are displayed in tables and charts.
For example, you can display dates in a standard European or US format based on the data modeling
setting Forma
ormatt P
Pa
att
ttern
ern. These are some examples of formats you can use:
Forma
ormatt mask

Description

YYYY or yyyy

four digit year such as 2017

YY or yy

last two digits of year such as 17

M

month with no leading zero 1-12

MM

Two digit month 01-12

MMM

Three letter month such as Jan

D

Day of year without a leading zero 0-365

DD

Day of year with up to one leading zero 01-365

ThoughtSpot Administration Guide

Page 114

Set number, date, and currency formats

Forma
ormatt mask

Description

DDD

Day of year with up to two leading zeroes 001-365

d

Day of month with no leading zero 1-31

dd

Two digit day of month 01-31

HH

Two digit 24 hour representation of hour 00-23

hh

Two digit 12 hour representation of hour 01-12

H

24 hour representation of hour with no leading zero 0-23

h

12 hour representation of hour with no leading zero 1-12

mm

Minutes 00-59

m

Minutes with no leading zero 0-59

ss

Seconds 00-59

s

Seconds with no leading zero 0-59

a

AM/PM indicator

December 09, 2017

Valid delimiters include most non-alphabet characters. This includes but is not limited to:
•
•
•
•
•
•
•

\
/
|
:
_
=

(forward slash)
(backward slash)
(pipe symbol)
(colon)
(dash)
(underscore)
(equal sign)

Examples of valid format masks you can produce for display are as follows:
•
•
•
•
•

MM/dd/yyyy
MMM
DD/MM/yyyy
MM/dd/yyyy HH:mm
DD/MM/yyyy HH:mm

To change the date format used to display a column’s values for a single table or, by editing the data
model, for the entire ThoughtSpot instance.
1. Decide if the change is for a table or the entire instance.
2. Find the Forma
ormatt P
Pa
att
ttern
ern for the column. This is either a column in a single table or a column in
the data modeling file.
3. In the column, enter the format you want to use.
4. Save your changes. If you are using a data-modeling file you’ll need to upload the new file to
your installation.

ThoughtSpot Administration Guide

Page 115

Set number, date, and currency formats

December 09, 2017

Set curr
currenc
ency
y fforma
ormatt
You can set a format for how currencies are displayed in tables and charts when using the ThoughtSpot
Data API or embedding. For example, you can display currencies in a standard European Euro or US Dollar
format based on the data modeling setting Curr
Currenc
ency
yT
Type
ype.
You can change the currency format used to display a column’s values for a single table. When you
specify the currency type of your data on the DATA page, your currency data will only display the correct
format and currency code in the embedded use case. Currency specific symbols are available in the nonembedded use case as well, but they are not localized.
All users are treated as if they are in en-US locale unless they are in embed mode and their browser
configuration tells ThoughtSpot that they are in some other locale. For example, 100 Polish Zloty
appears as 100zł to a user in Poland, but without localization enabled, it appears as PLN 100.
This subtle difference can be seen when you use the REST API. See the ThoughtSpot Application
Integration Guide for more information on the API.
1. Find the Curr
Currenc
ency
yT
Type
ype for the column whose display format you want to change.
2. Click on it to open the Specify Curr
Currenc
ency
yT
Type
ype menu.

3. Select one of the following ways you would like to change the format.
Option

Description

Inf
Infer
er
Fr
From
om
Br
Bro
owser

Your currency data will be modeled upon the locale of your browser setting.

Fr
From
om a
column

Your currency data will be modeled upon the existing currency information in the
selected column This option is disabled if there is no VARCHAR column to choose
from.

ThoughtSpot Administration Guide

Page 116

Set number, date, and currency formats

December 09, 2017

Option

Description

Specify
ISO
Code

Your currency data will be modeled upon your selection from the available currency code choices.

4. Click Ok to save your changes.

Rela
elatted inf
informa
ormation
tion
Model the data for searching

ThoughtSpot Administration Guide

Page 117

Change the Attribution Dimension

December 09, 2017

Change the A
Attribution
ttribution Dimension
Summary: The **Attribution Dimension** setting applies only to tables
that are related through a chasm trap. If your schema does not include
these, you can ignore this setting.
The Attribution Dimension setting only applies to tables that join over a Chasm Trap. By default, the
attribution dimension setting will be set to YES, but you can override that by setting the column’s
attribution dimension property to NO, as described here.

Unders
Understand
tand chasm tr
traps
aps and a
attribut
ttribute
e
dimension
In the classic chasm trap, two fact tables are related through a shared dimension table. When the two fact
tables are joined, the shared column(s) in the dimension table are used to attribute rows in one fact table
to match with rows in the other fact table.
Usually, all goes well using this method. But sometimes an incorrect or illogical attribution can result. This
can happen because the column chosen is not meaningful for performing this attribution. If you are seeing
unexpected results in searches that include tables across a chasm trap, this setting is for you.
Below is an example of a column that is not an attribution dimension. Suppose you have two fact tables,
Wholesale Purchases and Retail Sales, that share a common dimension Date.

In this example, the date column in the Date dimension should not be used for attribution, since unrelated
rows in both of the fact tables could share the same row in the Date table. Why? Because if Sally bought
oranges wholesale on April 25, 2005 and made a retail sale of apples on the same day, there is no logical
relationship between those two events. Combining the two events using the date they share will not
create any meaningful information.
If matching rows in two fact tables over a chasm trap depends on the values in a column contained in a
dimension table, that column is known as an attribution dimension.

ThoughtSpot Administration Guide

Page 118

Change the Attribution Dimension

December 09, 2017

In this example, the Product ID column in the Products dimension table is an attribution dimension. For
rows where the Product ID in the Wholesale Purchases and in the Retail Sales tables is a match, those
rows are logically related in a meaningful way. They can be combined in charts and reports to produce a
logical, expected outcome.

Ho
How
w tto
o set a
attribut
ttribute
e dimension
You cannot configure this setting in the model file. You can only configure it on a table-by-table basis. To
designate a column as not being an attribution dimension (i.e. not producing any meaningful attribution
across a chasm trap):
1.
2.
3.
4.

Find the column that is not an attribution dimension.
Select its Attribution Dimension
Dimension.
Set the value to NO. If you’re using the modeling file, set it to FALSE
ALSE.
Save your changes.

Rela
elatted inf
informa
ormation
tion
Model the data for searching

ThoughtSpot Administration Guide

Page 119

Link tables using relationships

December 09, 2017

Link tables using rrela
elationships
tionships
You can link tables by creating relationships between their columns. Linked tables can be searched
together or combined into a worksheet for easy searching. Tables that have no relationship between their
columns can not be combined in a single search.
There are two ways to create relationships between tables:
1. Create a constraint using TQL.
2. Create a relationship through the web interface.
The two methods create the same kind of relationship both from an end user perspective and an
administrative perspective. When creating a relationship between two tables, the columns that form the
link must be the exact same data type. For example, a column of type INT32 to another INT32 column.
Both types of relationships exist within the database. You can also generate a script through TQL that
contains all relationships, whether create via the web interface or in TQL.
Relationships created through either method can be managed either via TQL or by going to the
Rela
elationships
tionships page when viewing data in the Da
Datte Modeling section in the ThoughtSpot application. You
can view, modify, or delete relationships in either place.
You may create relationships using a mixture of TQL and the web interface, but the relationships you
create cannot form a circular relationship, or “cycle”. If you attempt to create a relationship that would
complete a cycle, you will see a message saying that the relationship could not be added because it
conflicts with another existing relationship.

ThoughtSpot Administration Guide

Page 120

Create a relationship

December 09, 2017

Cr
Crea
eatte a rrela
elationship
tionship
Summary: Explains how to create a link between two data sources
through a relationship.
You can quickly create a relationship (or link) between tables that allows you to combine them in a single
search. Choose a column to join on that both tables contain (e.g. employee ID or product key).
You must have either administration privilege or modify access permission to the columns to create a
relationship.
When creating a link between the columns in two data sources, the columns being linked must have the
same data type, with the same meaning. That is, they must represent the same data. Normally, you’ll make
this kind of link from a fact table column to a column in a dimension table that uniquely identifies a logical
entity in your data such as Employee ID for a person, Product ID for a product, or Date Key for a specific
date in a date lookup table.
To create a relationship through the Web interface:
1. Click on DATA, on the top navigation bar.

2. Click on the name of the data source you want to link from.
3. Select Rela
elationships
tionships.

4. If there are already some existing relationships, scroll down and click Add R
Rela
elationship
tionship.
Otherwise, continue to the next step.
5. Click on Sour
Sourc
ce C
Column
olumn and select the column you want to link in the source table.

ThoughtSpot Administration Guide

Page 121

Create a relationship

December 09, 2017

6. Under Des
Destina
tination
tion T
Table
able find and select the table that you want to link to.

7. Click on Des
Destina
tination
tion C
Column
olumn and select the column you want to link to in the destination table.

ThoughtSpot Administration Guide

Page 122

Create a relationship

December 09, 2017

8. Click Add K
Ke
ey to add the link.
9. Name your relationship and optionally give it a description.

10. Click Add R
Rela
elationship
tionship.
11. Repeat these steps for creating a link until all the links you want to make for your table have
been created.

ThoughtSpot Administration Guide

Page 123

Delete a relationship

December 09, 2017

Delet
Delete
e a rrela
elationship
tionship
Summary: You can delete relationship (link) between tables through
the application or TQL.
You must have either administration privilege or modify access permission to the columns to delete a
relationship. If you created a relationship (link) between tables using the Web interface, you can also
delete it from the Web interface. But if the relationship was created using TQL, you must also use TQL to
delete it.
To delete a relationship using TQL, use an ALTER TABLE...DROP FOREIGN KEY... statement. To delete a
relationship from the Web interface:
1. Click on the DATA icon on the top navigation bar and then on Worksheets
orksheets.

2. Click on the name of the data source you from which you want to remove the relationship.
3. Select Rela
elationships
tionships.

4. Find the relationship you want to delete, and click Delet
Delete
e.

ThoughtSpot Administration Guide

Page 124

Delete a relationship

ThoughtSpot Administration Guide

December 09, 2017

Page 125

About stickers

December 09, 2017

About sstick
tickers
ers
Summary: Stickers enable you to create categories for classification of
objects, including pinboards, answers, data sources, and worksheets.
You can create stickers to make it easier for people to find data sources and pinboards. Stickers are global
in scope. This means that everyone can see the stickers and use them to tag objects. They can also filter
lists of objects by sticker. Stickers are often used to designate subject areas, such as sales, HR, and
finance, but you can use them any way you like.
Keep in mind these permissions when working with stickers:
• Only administrators can create stickers.
• Anyone can apply a sticker.
• Anyone can filter by a sticker.

Cr
Crea
eatte a sstick
ticker
er
Only administrator users can create stickers. Anyone can apply the stickers you create, or use them as
filters when selecting from a list of sources or pinboards.
To create a sticker:
1. Navigate to the Manage Da
Data
ta or Pinboar
Pinboards
ds screen using the icons in the top navigation bar.
2. Choose Select sstick
ticker
er, scroll to the bottom of the list, and click + A
Add
dd.

3. Type the name for the new sticker.
4. You can change the name or color of a sticker by clicking the edit icon next to its name.

ThoughtSpot Administration Guide

Page 126

About stickers

December 09, 2017

Apply a sstick
ticker
er
Only administrators create stickers, but anyone with edit privileges can tag an object with a sticker.
To tag an object with a sticker:
1. From the top menu, choose Answers, Pinboards, or Data.

2. Find the item(s) you want to tag in the list, and check the box next to its name.
3. Click the apply sticker icon and choose one from the list. You can apply as many stickers as you
like to an object.

Filt
Filter
er b
by
y sstick
tickers
ers
Whenever you are selecting objects from a list, you can filter by sticker to find what you’re looking for.
Anyone can use stickers to filter lists of pinboards or data sources. You can also filter by sticker when
selecting data sources.
To filter by sticker:

ThoughtSpot Administration Guide

Page 127

About stickers

December 09, 2017

1. From the top menu, choose Ans
Answ
wers
ers, Pinboar
Pinboards
ds, or Da
Data
ta.

2. Click on Select sstick
ticker
er, and select a sticker to filter by. Click on its name.

ThoughtSpot Administration Guide

Page 128

Simplify search with worksheets

December 09, 2017

Simplify sear
search
ch with w
worksheets
orksheets
Summary: Worksheets are flat tables created by joining columns from
a set of one or more tables or imported datasets.
After modeling the data, create worksheets to make searching easier. For example, a sales executive might
need to search for information about retail sales. The required data could be contained in several tables
(sales, customers, products, stores, etc.), with foreign key relationships between them. An administrator
who is familiar with the data model can create a retail sales worksheet, that combines all of the related
fact and dimension tables into a single, easy-to-use view, and share it with the sales executive. This
provides access to the data without requiring an understanding of how it is structured.

Guidelines ffor
or w
worksheets
orksheets
Users are often unfamiliar with tables and how they are related to one another. A worksheet groups
multiple related tables together in a logical way. You might use a worksheet for these reasons:
•
•
•
•
•

To
To
To
To
To

pre-join multiple tables together.
give a user or group access to only part of the underlying data.
include a derived column using a formula.
rename columns to make the data easier to search.
build in a specific filter or aggregation.

Typically, you create one worksheet for each set of fact and dimension tables. For example, you may have
a sales fact table and an inventory fact table. Each of these fact tables shares common dimensions like
date, region, and store. In this scenario, you would create two worksheets: sales and inventory. The
following diagram depicts the workflow for creating the sales worksheet.

ThoughtSpot Administration Guide

Page 129

Simplify search with worksheets

December 09, 2017

The process for creating a worksheet is:
1.
2.
3.
4.
5.
6.
7.
8.
9.

Decide which tables to use for the worksheet.
Create a new worksheet.
Add sources (tables) to the worksheet.
Choose the inclusion rule to apply.
Choose the worksheet join rule.
Select the columns to include.
Optionally create formulas.
Save the worksheet.
Share the worksheet with groups or users.

An alternative way to create a worksheet is to do a search and save it as a worksheet. See the
ThoughtSpot User Guide for details on how to do this.

Cr
Crea
eatte a w
worksheet
orksheet
Create a worksheet to make the data easy for users to search. This process includes adding a new
worksheet, after which you will choose the data sources to include in it.
To create a new worksheet:
1. Click on DATA, on the top navigation bar.

2. Click the Actions icon from the upper right side of the screen, and select Cr
Crea
eatte w
worksheet
orksheet.

ThoughtSpot Administration Guide

Page 130

Simplify search with worksheets

December 09, 2017

Add sour
sourc
ces and c
columns
olumns tto
oaw
worksheet
orksheet
After creating a worksheet, you need to add the sources that contain the data. Sources is another name
for tables. The sources you choose are typically related to one another by foreign keys.
To add the sources to the worksheet:
1. Click on the Choose Sour
Sourc
ces link.

ThoughtSpot Administration Guide

Page 131

Simplify search with worksheets

December 09, 2017

2. Check the box next to each of the sources you want to include in the worksheet.
Note that the list of sources only shows the tables on which you have view privileges.

3.
4.
5.
6.

If you want to see what the data inside the sources looks like, click Explor
Explore
e all da
data
ta.
Choose the inclusion rule.
Choose the worksheet join rule.
Click Done to save your changes.

7. Expand the table names under Columns to select the columns to add to the worksheet.
a. To add all of the columns from a table, click on the table name and click + A
Add
dd
Columns
olumns.
b. To add a single column, double click on its name.
c. To add multiple columns, Ctl+click on each column you want to add and click + A
Add
dd
Columns
olumns. Note that once you add a column, non-related tables (i.e. those without a
primary/foreign key relationship) become hidden. If you are working with two tables
that should be related, but are not, you can add a relationship between them.
8. Click on the worksheet title to name it, and then Sa
Sav
ve it.
9. Click on each column name to give it a more user-friendly name for searching. You can tab
through the list of columns to rename them quickly.
10. If you want to add a prefix to the name of several columns, select them, click the Add Pr
Prefix
efix
button, and type in the prefix.

ThoughtSpot Administration Guide

Page 132

Simplify search with worksheets

December 09, 2017

11. Click Actions and select Sa
Sav
ve.

12. Share your worksheet, if you want other people to be able to use it.

Wher
here
e tto
o go ne
next
xt
• Ho
How
w the inclusion rule w
works
orks
Use the inclusion rule to specify which data to include in a worksheet where two or more tables
are joined. If you are familiar with SQL, you might think of it as a JOIN condition.
• Ho
How
w the w
worksheet
orksheet join rule w
works
orks
Use the worksheet join rule to specify when to apply joins when a search is done on a
worksheet. You can either apply joins progressively, as each search term is added
(recommended), or apply all joins to every search.

ThoughtSpot Administration Guide

Page 133

How the inclusion rule works

December 09, 2017

Ho
How
w the inclusion rule w
works
orks
Summary: Use the inclusion rule to specify which data to include in a
worksheet where two or more tables are joined. If you are familiar with
SQL, you might think of it as a JOIN condition.
In the case where some of the rows in a fact table do not have a match in any dimension tables, the
inclusion rule determines whether or not the rows are shown. Because of this, the inclusion rule can affect
the number of rows the worksheet will contain. The inclusion rule is important if some table values are
empty (or NULL) or if some primary key column values in a fact table do not have a match to a foreign
key in the dimension table. In these cases, how you set an inclusion rule affects the number of rows in the
worksheet.
Only rows in the fact table (also known as the LEFT table) are affected by the inclusion rule. It works like
this:
If y
you
ou choose

Then…

Apply full out
outer
er join
(Full Out
Outer
er Join)

The results of both the left and right outer joins are combined, and all
matched or unmatched rows from the tables on both sides are shown.

Apply left out
outer
er join
(L
(Left
eft Out
Outer
er Join)

All possible rows in the fact table are shown, regardless of whether they have
a match in the dimension tables.

Apply right out
outer
er join
(Right Out
Outer
er Join)

All possible rows in the second table are shown, regardless of whether they
have a match in the dimension tables.

Ex
Exclude
clude empty rro
ows
(Inner Join)

Any rows that do not have a match in one of the dimension tables, won’t be
shown in search results.

When using Ex
Exclude
clude empty rro
ows (Inner Join)
Join), the number of rows in the resulting worksheet can differ
from the number of rows in the table when accessing it directly, because of the join condition. The
worksheet acts like a materialized view. This means that it contains the results of a defined query in the
form of a table.
If you find that the charts and tables built on a worksheet contain a large number of null values (which
display as {blank} in the web browser), you can fix this by changing the inclusion rule for the worksheet.
The answer returned when searching using a worksheet as the source can be different from the answer
you get when using the table directly as a source. When using a worksheet as a source, even if you were
to select fields that come from only one table in your search, any underlying joins to other tables will still
be active. When using the table directly as the source, you will see every value.
This is best understood through an example.
A typical sales fact table contains a column with the employee ID of the person who made the sale. The
employee ID column has a foreign key in the employee dimension table. This is the relationship used to
join the two tables.
Sometimes a sale has been made directly or through a reseller, without involving a sales person. In this
case, the employee ID value for the sale will be empty in the fact table. If you wanted the worksheet to
include all sales, regardless of whether or not they were associated with a sales person, you would choose
Include all rro
ows (L
(Left
eft Out
Outer
er Join)
Join). If you only want the worksheet to contain sales made by employees, you
would choose Ex
Exclude
clude empty rro
ows (Inner Join)
Join).

ThoughtSpot Administration Guide

Page 134

How the worksheet join rule works

December 09, 2017

Ho
How
w the w
worksheet
orksheet join rule w
works
orks
Use the worksheet join rule to specify when to apply joins when a search is done on a worksheet. You can
either apply joins progressively, as each search term is added (recommended), or apply all joins to every
search.

Unders
Understand
tand pr
progr
ogres
essiv
sive
e joins
Often, a worksheet includes several dimension tables and a fact table. With progressive joins, if your
search only includes terms from the fact table, you’ll see all of the rows that satisfy your search. But as you
add terms from dimension tables, the total number of rows shown may be reduced, as the joins to each
dimension table are applied. It works like this:
• If you choose Apply joins pr
progr
ogres
essiv
sively
ely (r
(rec
ecommended
ommended ffor
or mos
mostt cases
cases)), joins are only applied
for tables whose columns are included in the search.
• If you choose Apply all joins
joins, all possible joins are applied, regardless of which tables are
included in the search.
When using Apply joins pr
progr
ogres
essiv
sively
ely, the number of rows in a search using the worksheet depends on
which tables are part of the search. The worksheet acts like a materialized view. This means that it
contains the results of a defined query in the form of a table. So if a particular dimension table is left out
of the search, its joins are not applied.

Rule-Based R
Ro
ow L
Le
evel Security (RLS) with
worksheets
With Rule-Based RLS, you need to protect every table that contains any sensitive data. To do this, you’ll
grant access by creating explicit row level security rules on each of the underlying tables which contain
data that row level security should apply to.
When creating the row level security rules for a table that’s part of a worksheet, you aren’t limited to
referencing only the columns in that table. You can specify columns from other tables in the worksheet as
well, as long as the tables are joined to the table you’re creating the rule on. Then, when creating a
worksheet on top of them, the behavior is consistent regardless of the worksheet join rule you choose.
Users will never be able to see data they should not, regardless of what their search contains.
Imagine you have a worksheet that contains a “Sales” fact table, and “Customer” and “Product”
dimensions that are joined on “Customer SSN” and “Product Code” columns. In order to secure the “Sales”
table, you can use “Customer Name” from the “Customer” column to create a row level security rule.

Ho
How
w joins ar
are
e applied with chasm tr
traps
aps
When working with worksheets and row level security, you need to understand how joins are applied. This
is particularly important with chasm trap schemas. For chasm trap schemas, if row level security is only
set on one of the tables, people could see data they should not see if the scope of their search does not
include that table. (this protects them from having people see the wrong things if they have chasm trap).
For chasm trap worksheets, progressive and non-progressive joins do not apply. There is an entirely
different methodology for how worksheet joins on a chasm trap schema work with row level security. So
you can safely ignore that setting.

ThoughtSpot Administration Guide

Page 135

How the worksheet join rule works

December 09, 2017

Joins and aggr
aggrega
egatted w
worksheets
orksheets
You have the ability to join an aggregated worksheet with a table. You can join an aggregated worksheet
with a system table by creating a relationship. This means aggregated worksheets behave similar to tables,
and they can be used in the same way as a table, excluding any TQL manipulation. You also have the
capability to create a worksheet on top of an aggregated worksheet. So aggregated worksheets can be
included as tables in regular worksheets.

ThoughtSpot Administration Guide

Page 136

Create a formula in a worksheet

December 09, 2017

Cr
Crea
eatte a fformula
ormula in a w
worksheet
orksheet
Summary: You can define formulas and use them to create derived
columns in worksheets.
You create formulas by combining standard functions and operators, column names, and constant values.
Anyone who can create a worksheet can add a formula to it. Formulas are not reusable; the formula you
create is associated only with the worksheet it belongs to. A complete list of available formulas and
examples of each is available in the Formula reference.
You can create a formula in a worksheet by using the Formula Builder. When you do this, the result of the
formula gets added to the worksheet as a column. Use these steps to create a formula:
1. Create a new worksheet, or edit an existing one.
2. Click the + button next to Formulas
ormulas.

d
3. Type your formula in the Formula Builder.

ThoughtSpot Administration Guide

Page 137

Create a formula in a worksheet

December 09, 2017

Not
Note:
e: Formulas elements are color coded by type and can include the formula operators and
functions (blue), the names of columns (purple), and/or constants (black).
4. If you want to change what your formula returns, use the Adv
dvanc
anced
ed settings
settings.
Depending on your formula, you may be able to change:
• Data type
• ATTRIBUTE or MEASURE
• Aggregation type

ThoughtSpot Administration Guide

Page 138

Create a formula in a worksheet

December 09, 2017

5. You can see a list of formula operators with examples by clicking on Formula As
Assis
sistant.
tant.

6. Name the formula by clicking on its title and typing the new name. Click Sa
Sav
ve.

ThoughtSpot Administration Guide

Page 139

Edit or rename worksheet

December 09, 2017

Edit or rrename
ename w
worksheet
orksheet
Summary: A worksheet can be edited by anyone with the proper
permissions.
Yu can always go into a worksheet and make changes such as adding sources and columns, adding or
editing formulas, and changing column names. You can also rename a worksheet.

Edit a w
worksheet
orksheet
To edit a worksheet:
1. Click on the DATA icon on the top navigation bar and then on Worksheets
orksheets.

2. Click on the name of the worksheet you want to edit from the list.
3. Click the Edit button in the upper right hand side of the screen.
4. Make your changes to the worksheet.
5. Click Actions and select Sa
Sav
ve.

ThoughtSpot Administration Guide

Page 140

Edit or rename worksheet

December 09, 2017

Rename a w
worksheet
orksheet or table
You can change a worksheet or table name from the ThoughtSpot application.
To change the name of a worksheet or table:
1. Click on DATA, on the top navigation bar.

2. Find the worksheet or table you want to rename and click on its name.
3. On the right hand side, click the current name, and enter a new name.

You can also edit column names and other details in the same way.
4. Click Done and Sa
Sav
ve.

Rela
elatted inf
informa
ormation
tion
Change the inclusion or join rule for a worksheet

ThoughtSpot Administration Guide

Page 141

Change inclusion, join, or RLS for a worksheet

December 09, 2017

Change inclusion, join, or RLS ffor
or a
worksheet
Summary: As long as you have permissions to edit a worksheet, you
can always go into it and set a different inclusion rule or join rule.
If you find that the charts and tables built on a worksheet contain a large number of null values (which
display as {blank} in the web browser), you can fix this by changing the inclusion rule for the worksheet.
if you have the Can A
Adminis
dministter RLS privilege, or belong to a group who does, you can create a worksheet
that bypasses the RLS rules underlying a worksheet’s data. When by pass is set the underlying RLS allows
users, that would not otherwise be unable, to see an aggregate/market view of a tables data.

Change/c
Change/configur
onfigure
eaw
worksheet
orksheet
Before working through this procedure, make sure you are familiar with how the following affect data:
• inclusion rule
• worksheet join rule
• role-level security (RLS)
To configure these values for a worksheet:
1. Click on the DATA icon on the top navigation bar and then on Worksheets
orksheets.

2.
3.
4.
5.

Click on the name of the worksheet you want to edit from the list.
Click the Edit button in the upper right hand side of the screen.
Click on the Choose Sour
Sourc
ces link.
Scroll to the bottom of the dialog.

6. Configure the inclusion rule, worksheet join rule, and RLS as needed.

ThoughtSpot Administration Guide

Page 142

Change inclusion, join, or RLS for a worksheet

December 09, 2017

7. Click Done
Done.
8. Click Actions and select Sa
Sav
ve.

ThoughtSpot Administration Guide

Page 143

Delete a worksheet or table

December 09, 2017

Delet
Delete
eaw
worksheet
orksheet or table
Summary: When you try to delete a worksheet or table, you'll see a
message listing any dependent objects that must be removed first.
ThoughtSpot checks for dependencies whenever you try to remove a table or worksheet. A list of
dependent objects is shown, and you can click on them to delete them or remove the dependency. Then
you’ll be able to remove the table or worksheet.
To delete a worksheet or table:
1. Click on DATA, on the top navigation bar.

2. Find the worksheet or table you want to remove in the list, and check the box next to its name.
3. Click the Delet
Delete
e icon.

If you are attempting to delete a data source with dependent objects, the operation will be
blocked. You will see a warning, with a list of dependent objects with links.
4. Click on the link for an object to modify or delete it. When all its dependencies are removed, you
will be able to delete the data source.

ThoughtSpot Administration Guide

Page 144

Delete a worksheet or table

December 09, 2017

5. You can also click on the name of a worksheet or table and then click Dependents
Dependents, to see a list
of dependent objects with links.
The Dependents list shows the names of the dependent objects (worksheets and pinboards),
and the columns they use from that source. You can use this information to determine the
impact of changing the structure of the data source or to see how widely used it is. Click on a
dependent object to modify or delete it.

ThoughtSpot Administration Guide

Page 145

Understand groups and privileges

December 09, 2017

Unders
Understand
tand gr
groups
oups and privileges
Summary: Creating groups and assigning users to them makes
privilege management easier.
Before people can log in and use ThoughtSpot, you need to create a username, a password, and a
membership in one or more groups for them.
This page describes manual creation of users, groups, and privileges, but you can also manage users
through LDAP or SAML. For information on setting up SAML authentication, see the ThoughtSpot
Application Integration Guide.

Privileges and gr
groups
oups
Privileges determine what kinds of actions users are allowed to do. You assign privileges to groups. Then,
you create users and assign them to groups. This is how you grant users access to different capabilities in
ThoughtSpot.
Each group includes a set of privileges for its users. The privileges a group has determine the actions that
its members are allowed to do. If a user belongs to more than one group, they will have the highest level
of the privileges from all the groups they belong to. Plan your groups so that you can use them to assign a
common set of privileges to multiple users. Good planning will pay off in ease of administration and a
better search experience.
There is a default group called All
All, which includes every user in ThoughtSpot. When you create a new user,
they will be added to the All group automatically. You cannot delete the All group or remove members
from it.
You can also have a hierarchy of groups. That is, groups can belong to (that is, be children of) other
groups. When using group hierarchies, permissions are inherited from the parent group. So if you’re a
member of a sub-group, you would automatically have the privileges of the parent group.

Lis
Listt of privileges
Here are the different privileges, and the capabilities they enable:
Privilege

Description

Has adminis
administr
tra
ation
privileges

Can manage Users and Groups and has view and edit access to all data.
Users with this privilege can also download a saved answer.

Can upload user da
data
ta

Can upload their own data from the application's DATA page using Actions
> Upload da
data
ta.

Can do
download
wnload da
data
ta

Can download data from search results and pinboards.

Can shar
share
e with all
users

Can see the names of and share with users outside of the groups the user
belongs to.

Can manage da
data
ta

Can create a worksheet. Can also create an aggregated worksheet from the
results of a search by selecting Sa
Sav
ve as w
worksheet
orksheet. Can also use

ThoughtSpot Administration Guide

Page 146

Understand groups and privileges

Privilege

December 09, 2017

Description
ThoughtSpot Data Connect, if it is enabled on your cluster.

Can schedule pinboar
boards
ds

Can create pinboard schedules and edit their own scheduled jobs.

Has Spot IQ privilege

User can use SpotIQ's auto analyze function.

Can A
Adminis
dministter RLS

Users in groups with this privilege (directly or indirectly) can bypass rowlevel security (RLS) rules. This privilege can only be assigned by a user who
already Has adminis
administr
tra
ation privilege
privilege. Your installation configuration may enable or disable this feature. By default, it is enabled.

Typically, the ALL group has a common set of privileges applies such as the Can upload user da
data
ta and/or
Can do
download
wnload da
data
ta privileges.
Privileges are additive, meaning that if a user belongs to more than one group, they will have the highest
level of privileges from among the groups they are a member of. They are also inherited from the parent,
so that a sub-group gets all the same privileges of its parent, all the way up the group hierarchy.
If you add the privilege Has adminis
administr
tra
ation privileges to a group, note that all users in that group will be
able to see all the data in ThoughtSpot. Administrators can see all data sources, and Row level security
does not apply to them.
Permissions to see and edit tables, worksheets, and pinboards are set when you share them with users
and groups, as described in the topic Data security.

ThoughtSpot Administration Guide

Page 147

December 09, 2017

Understand groups and privileges

The following table shows the intersection of user privilege and ability:

d
oa
pl
U

a
at
D

Y
Y

Y

Y

N

Y

Y

Y

Y

Y

N

N

N

N

Y

N

N

N

N

N

Y

N

N

N

Y4

N

Y3

Y2

Y4

Y4

Y4

Y4

Y4

Y4

Y4

Y

D
rU
C

N

N

N

N

Y5

N

N

Y

d
ea
R

N

N

N

N

Y

N

N

Y

e
Se

N

N

N

N

N

N

N

Y

in
Jo

N

N

N

N

Y

N

N

Y

N

N

Y

N

N

N

N

Y

N

N

N

Y

N

N

N

Y

er
w
ie
V

Y
N
N
N

N

N

N

N

s
ol
C

Y
N
N
Y

N

N

Y

N

ct
ze
ly
ne
r
le
na
on
u
A
C
d
ohe
ut
Sc
A
se
U

se
U

Admin
N
N
Y
N

N

Y

N

a
at
D

Can Upload Data
N
Y
N
N

N

Y

se
U

Can Download Data
Y
N
N

N

N

a
m
he
Sc

Data Management
N
N
N

N

ith
w

Can Auto-Analyze
N
N

N

ps
ps
hi
hi
ns
ns
io
io
at
at
el
el
R
R

n
de
id
H

Can Schedule
N
N

1
.
up
ps
ro
S
a
S
o
l
G
l
at
W
W
Pr
A
D
in
ta
it
l.
a
o
d
gg
s
ith
ith
D
Ed
C
A
le
oa
w
w
d
l
e/
e
fy
ru
n
e
e
i
at
at
oa
ar
ar
od
ow
pl
re
re
LS
C
C
M
U
D
Sh
Sh
R

Can Share with All
N

Applies to non-owners only.
Any tables.
Author of at least one table in relationship.
Only when read permission for columns used in the relationship.
With edit permission.

None

Table notes:
1.
2.
3.
4.
5.

Page 148

ThoughtSpot Administration Guide

Understand groups and privileges

December 09, 2017

Rela
elatted inf
informa
ormation
tion
• Add a group and set security privileges
• Add a user

ThoughtSpot Administration Guide

Page 149

Create, edit, or delete a group

December 09, 2017

Cr
Crea
eatte, edit, or delet
delete
e a gr
group
oup
Summary: Good planning when creating groups and assigning
privileges will pay off in ease of administration and a better search
experience.
Before adding users, create the groups they will belong to. Each group includes a set of privileges for its
users.

Cr
Crea
eatte a gr
group
oup
To create a group and add privileges for the group:
1. Log into ThoughtSpot from a browser.
2. Click on the Admin icon, on the top navigation bar.

3. In the Admin panel, click on User Management and Gr
Groups
oups.

4. Click the + A
Add
dd Gr
Group
oup button on the upper right hand side of the list of groups.

ThoughtSpot Administration Guide

Page 150

Create, edit, or delete a group

December 09, 2017

5. Enter the details for the new group:

Field

Description

Gr
Group
oup name

Enter a unique name for the group.

Displa
Display
y name
Sharing
visibility

Indicate whether objects can be shared with this group. When set to
SHAREABLE
SHAREABLE, this group is an option in the Shar
Share
e dialog.

Description

Optionally enter a description.

Privileges
Check the privileges you want to grant to the group. If you add the privi-

ThoughtSpot Administration Guide

Page 151

Create, edit, or delete a group

December 09, 2017

lege Has adminis
administr
tra
ation privileges to a group, all users in that group can
see all the data in ThoughtSpot. Administrators can always see all data
sources, and Row level security does not apply to them.

6. Click the Manage Gr
Groups
oups tab if you want to add sub-groups.
Find the groups you want to add in the list, or search for them by name. Check the box next to
each group you want to add to the group.
7. Click the Manage Users tab if you want to add users.
Find the users you want to add in the list, or search for them by name. Check the box next to
each user you want to add to the group.
8. Click Add to create the group.

Edit a gr
group
oup or delet
delete
e a gr
group
oup
After adding a group, you can always go in and edit its settings to add or revoke privileges. The new
settings will apply to all the group members. When editing a group, keep in mind that only sub-groups
appear in a group:

The No Gr
Groups
oups in Gr
Group
oup only indicates there are no children in this group’s hierarchy. There may be a
parent. This group inherits all the privileges of any parent group it may have. Keep this in mind when
adding users.
To edit or delete an existing group:
1. Log into ThoughtSpot from a browser.
2. Click on the Admin icon, on the top navigation bar.
3. In the Admin panel, click on User Management and Gr
Groups
oups.

ThoughtSpot Administration Guide

Page 152

Create, edit, or delete a group

December 09, 2017

4. Find the group you want to edit in the list and click its name, or the edit icon

.

If you don’t see the name of the group, try searching for it. You can also delete a group from this
page by clicking the Delet
Delete
e icon. Deleting a group does not delete its users.
5. Make your changes and click Upda
Updatte.

Add multiple users tto
o a gr
group
oup
You can add multiple users to a group using one button. To add multiple users to a group:
1. Log into ThoughtSpot from a browser.
2. Click on the Admin icon, on the top navigation bar.
3. In the Admin panel, click on User Management and Users
Users.

4. Select the users you would like to add to the same group from the list.
5. Click the Add Users tto
o Gr
Groups
oups button on the top of the list of users.

ThoughtSpot Administration Guide

Page 153

Create, edit, or delete a group

ThoughtSpot Administration Guide

December 09, 2017

Page 154

Add, edit, or delete a user

December 09, 2017

Add, edit, or delet
delete
e a user
You will create a user account for each unique person who will access ThoughtSpot, either manually or
through LDAP. If a user has access through LDAP, that user’s information is managed via your LDAP
installation. If you create a user manually in ThoughtSpot, you manage that user in ThoughtSpot.
You can edit manually created users through the interface. If a manually-created user forgets their
password, you can reset it by editing the user. If you have forgotten the admin password, please call
ThoughtSpot Support.

Cr
Crea
eatte a user thr
through
ough the int
interf
erfac
ace
e
This procedure shows how to creating a user manually. When you create a user, you can assign group
memberships. The group’s privileges and permissions apply to all of its members. Any user you create will
be added to the group All automatically.
1. Log into ThoughtSpot from a browser.
2. Click on the Admin icon, on the top navigation bar.

3. In the Admin panel, click on User Management and Users
Users.

4. Click the + A
Add
dd User button on the upper right hand side of the list of groups.

ThoughtSpot Administration Guide

Page 155

Add, edit, or delete a user

December 09, 2017

5. Enter the details for the new user:

Field

Description

Username
A login name for the user. Usernames must be unique and lowercase.
If you are using Active Directory to authenticate users, and your LDAP
configuration requires users to be created manually (i.e. they are not created automatically in ThoughtSpot upon authentication), the username
you specify has to be domain qualified (e.g.
username@ldap.thoughtspot.com), and you must enter a dummy password.

Displa
Display
y name

A unique name for the user (usually their first and last name).

Sharing
visibility

Indicate whether objects can be shared with this user. When set to
SHAREABLE
SHAREABLE, this user is an option in the Shar
Share
e dialog.

ThoughtSpot Administration Guide

Page 156

Add, edit, or delete a user

December 09, 2017

Change
pas
passswor
ord
d

A password.

Confirm
pas
passswor
ord
d

Enter the password again.

Email addr
addres
esss

The user's email address. This is used for notification when another user
shares something with them.

Manage gr
groups
oups
Select all the groups the user will belong to. If you add the user to a
group that has the privilege Has adminis
administr
tra
ation privileges
privileges, note that they
will be able to see all the data in ThoughtSpot.
When you create a new user, the groups they belong to define the user's:
• Privileges, the actions they are allowed to do, which are defined
when you Add a group and set security privileges.
• Permissions, the data they can access and view, which is defined when you Data security.
Administrators can see all data sources, and Row level security does not
apply to them.
6. Click Add to create the user.

Edit or delet
delete
e a user
After a user has been created, you can always go back and change their settings, for example to change
their group memberships or change their password. You can also change their name as long as it remains
unique
As an administrator, you can edit a user and change the groups the user belongs to. You can also edit a
user to reset a user’s password by entering and confirming the new password. This is useful if a user has
forgotten their password, or to effectively disable an account.
To edit an existing user:
1. Log into ThoughtSpot from a browser.
2. Click on the Admin icon, on the top navigation bar.

3. In the Admin panel, click on User Management and Users
Users.

ThoughtSpot Administration Guide

Page 157

Add, edit, or delete a user

December 09, 2017

4. Find the user you want to edit in the list and click on its name or the edit icon
don’t see the name of the user, try searching for it.

. If you

You can also delete a user from this page by clicking the Delet
Delete
e icon.
5. Make your changes and click Sa
Sav
ve.

ThoughtSpot Administration Guide

Page 158

Job management (scheduled pinboards)

December 09, 2017

Job management ((scheduled
scheduled pinboar
pinboards
ds))
Summary: All jobs on your cluster will appear on the Jobs Management
page. You can also view jobs for individual pinboards under the
pinboard Actions dropdown.
The Jobs Management page found on the Admin section in the ThoughtSpot web application allows you
to create and manage jobs, namely scheduled pinboards. Scheduled pinboards should help with preparing
for recurrent meetings, when reviewing the same pinboard is necessary. They should also be useful when
you have metrics you want to monitor at a consistent interval, like daily or monthly sales targets.
You can get pinboards emailed to you on a regular basis and do analysis offline. This introduces an
additional format for you to consume and share pinboards with others, including those who don’t have a
ThoughtSpot account.
Contact ThoughtSpot Support if scheduled pinboards is not enabled on your cluster, or you can run the
command tscli scheduled-pinboards to enable it yourself.

Scheduled pinboar
pinboard
d cr
crea
eattors
Administrators and users with can schedule pinboard privilege can schedule and manage pinboard jobs.
These scheduled pinboard creators must have at least edit-only and view-only rights to the pinboard they
want to share.
 Warning: It is recommended that admins carefully choose who to give can schedule pinboard privilege
to, since there is a possible security hole where a user with limited access can get a pinboard email with all
access data.

Row le
lev
vel security
The scheduled pinboards respect row level security rules. This means if the recipients are users in
ThoughtSpot, then they can only see data based on their own access to the pinboard. If the user does not
have at least view-only access to the pinboard, then they will not see anything in the email. However, if the
recipients are from outside of the cluster, then they will have access to the dataset of the pinboard based
on the sender’s permissions.

Scheduled pinboar
pinboard
d fforma
ormats
ts
The pinboard visualizations are attached to the scheduled email as CSV or PDF files. Saved configurations
such as pinboard filters are applied to the attachments. Refer to the table to see how the pinboard data is
represented in each file format.
CS
CSV
V

PDF

The CSV file gets data only for table visualizations.

The PDF file gets data for all visualizations.

The email has n CSV attachments, where there are n table visualizations in the pinboard.

The email has only one attachment
file, which includes every visualiza-

ThoughtSpot Administration Guide

Page 159

Job management (scheduled pinboards)

CS
CSV
V

December 09, 2017

PDF
tion on its own page.

Table visualizations have all data rows that they’re supposed to
have.

Table visualizations include only
the first 100 rows.

In the case of a corrupted pinboard: no email is sent. An error
message indicating failure to export data is visible on the Admin
Jobs Management page.

In the case of a corrupted pinboard: the PDF attachment has
empty/error screenshots.

In the case of a corrupted visualization: an email with the visualizations whose data can be exported is sent. An error message
indicating visualization export error is visible on the Jobs Management page.

In the case of a corrupted visualization: the PDF attachment has
empty/error slots for the corrupted visualizations.

The size of each email is limited to 25 MB, which matches most email services size limitations.
And the total number of recipients for a scheduled pinboard job cannot exceed the default of 1000.

Rela
elatted inf
informa
ormation
tion
For information on creating a pinboard, see the Schedule a pinboard job.

ThoughtSpot Administration Guide

Page 160

Scheduled pinboards management

December 09, 2017

Scheduled pinboar
pinboards
ds management
Summary: You can manage all scheduled pinboards on the Jobs
Management page under Admin.
Users who are not admins, but have can schedule pinboard privilege, can only view pinboard schedules
they’ve created. You can select specific jobs and choose to pause, resume, edit, or delete them. You can
have up to 50 scheduled jobs on your cluster at time. Contact ThoughtSpot Support if you’d like to
increase this limit.

Bulk actions
Select the scheduled pinboards and use the Delet
Delete
e, Resume
esume, and Pause buttons to perform these bulk
actions. Deleting a pinboard will also delete any schedules linked to it.

Job ssta
tatuses
tuses
Clicking on the row of a job will open a detailed view of every generated update of that job. You can see
the start and end times of the job, as well as the status. Clicking on a job will show more information about
the status updates.

ThoughtSpot Administration Guide

Page 161

Scheduled pinboards management

December 09, 2017

Pinboar
Pinboard
d links
Click the scheduled pinboard name link to jump to a Edit schedule page, where you can edit the schedule
configurations.
You can also click on the pinboard link provided in the scheduled pinboard emails to jump to the pinboard
in ThoughtSpot. In order to have the link direct you to the correct URL, you must first configure front end
host and port access. Contact ThoughtSpot Support to configure these settings.

ThoughtSpot Administration Guide

Page 162

Overview of security features

December 09, 2017

Ov
Overvie
erview
w of security ffea
eatur
tures
es
There are several aspects of security, including access and permissions, data security and privacy, and
security from an IT perspective.
• System Security refers to audit logs and security policies.
• Data Security refers to which users can see which data in the ThoughtSpot application, and
includes:
◦ Users and Groups
◦ Privileges
◦ Table and columns sharing
◦ Row level security
◦ Worksheet sharing
◦ Pinboard sharing
• Network Security refers to ports for external traffic and traffic within the cluster. Some ports
must remain open for handling network requests from outside the ThoughtSpot instance. To see
a list of network ports that must remain open to outside traffic, and for inter-cluster
communication, review the information in Network ports.

ThoughtSpot Administration Guide

Page 163

System security

December 09, 2017

System security
Summary: System security refers to audit logs and security policies.
ThoughtSpot includes a number of management tools, monitoring applications, and automated processes
to support system security. System security includes managing access and privileges, audit logs, security
policies, and Linux OS installed package updates.

Audit logs
There are several ways you can view audit log information in ThoughtSpot. You can see recent events in
the Control Center or view more detailed audit logs using tscli. Administrators can view audit logs of
configuration changes users have made to ThoughtSpot in these ways:
• Monitor events from the Control Center.
• Generate audit log reports through the tscli command.
You can access an audit log of cluster events through tscli. You can also access information on cluster
updates, configurations, data loading and metadata events.
Use the tscli event list command to return an audit list of events from the cluster. The syntax is:
tscli event list
[--include ]
[--since 
| --from 
--to ]
[--detail]
[--summary_contains
<'string1'| 'string2' ...>]
[--detail_contains
<'string1'| 'string2' ...>]
[--attributes
]
Optional parameters are:
Par
aramet
ameter
er

Description

--include

Specifies the type of events to include, and can be all, config, or
notification.

--detail

Returns the events in a detail format rather than a tabular summary, which
is the default.

--summary_contains
<'string1' |
'string2' ...>

Specifies a string to check for in the event summary. Enclose strings in single quotes, and separate multiple strings with &pipe;. Events that match all
specified strings will be returned.

--detail_contains
<'string1'|
'string2' ...>

Specifies a string to check for in the detail. Enclose strings in single quotes,
and separate multiple strings with | (pipe symbol). Events that match all
specified strings will be returned.

ThoughtSpot Administration Guide

Page 164

System security

December 09, 2017

Par
aramet
ameter
er

Description

--attributes


Specifies attributes to match as key=value pairs. Separate multiple attributes with | (pipe symbol). Events that match all specified key/value pairs will
be returned. Put single quotes around the value(s).

And a time window made up of either:
• --since  is a time in the past for where the event audit begins, ending
at the present time. Specify a human readable duration string, e.g. 4h (4 hours), 30m (30
minutes), 1d (1 day).
Or both:
• --from  is a timestamp for where to begin the event audit. It must be of the
form: yyyymmdd-HH:MM.
• --to  is a timestamp for where to end the event audit. It must be of the
form: yyyymmdd-HH:MM.
To get audit logs:
1. Log in to the Linux shell using SSH.
2. Issue the tscli event list command, with the desired parameters, for example:
$ tscli event list
--include config
--since 24 hours

Security policies
Security policies are the principles and processes ThoughtSpot uses in development to ensure a product
that conforms to security standards. Security policies ensure a secure product with each release. When a
release is in development, each build is tested using Qualys Network Security and Vulnerability
Management Suite. Issues and vulnerabilities are fixed proactively, based on the results.
The ThoughtSpot Engineering and ThoughtSpot Support teams are notified of Common Vulnerabilities
and Exposures (CVEs), so they can patch OS packages proactively as well. You can view installed
packages along with their version numbers at any time, in order to see if you require an update to
ThoughtSpot.
Whenever a CVE is identified, and an OS package needs to be updated, the next patch release will include
the patch or update. You can view installed Linux packages at any time, along with the version numbers of
the installed packages.

ThoughtSpot Administration Guide

Page 165

Data security

December 09, 2017

Da
Data
ta security
Summary: Data security refers to which users can see which data in
the ThoughtSpot application.
Sharing and security privileges govern what data a user can access and what they can do with the data.
Admins can use privileges to regulate access to information and provide a personalized user experience.

Users, gr
groups,
oups, and privileges
Data security applies to users and groups. Users can be managed manually or through LDAP. Each user
can have membership in one or more groups. Admins can make security settings that determine what
users are allowed to do in ThoughtSpot. These settings are applied at the group level.
The following table shows the intersection of user privilege and ability:

ThoughtSpot Administration Guide

Page 166

December 09, 2017

Data security

The following table shows the intersection of user privilege and ability:

d
oa
pl
U

a
at
D

Y
Y

Y

Y

N

Y

Y

Y

Y

Y

N

N

N

N

Y

N

N

N

N

N

Y

N

N

N

Y4

N

Y3

Y2

Y4

Y4

Y4

Y4

Y4

Y4

Y4

Y

D
rU
C

N

N

N

N

Y5

N

N

Y

d
ea
R

N

N

N

N

Y

N

N

Y

e
Se

N

N

N

N

N

N

N

Y

in
Jo

N

N

N

N

Y

N

N

Y

N

N

Y

N

N

N

N

Y

N

N

N

Y

N

N

N

Y

er
w
ie
V

Y
N
N
N

N

N

N

N

s
ol
C

Y
N
N
Y

N

N

Y

N

ct
ze
ly
ne
r
le
na
on
u
A
C
d
ohe
ut
Sc
A
se
U

se
U

Admin
N
N
Y
N

N

Y

N

a
at
D

Can Upload Data
N
Y
N
N

N

Y

se
U

Can Download Data
Y
N
N

N

N

a
m
he
Sc

Data Management
N
N
N

N

ith
w

Can Auto-Analyze
N
N

N

ps
ps
hi
hi
ns
ns
io
io
at
at
el
el
R
R

n
de
id
H

Can Schedule
N
N

1
.
up
ps
ro
S
a
S
o
l
G
l
at
W
W
Pr
A
D
in
ta
it
l.
a
o
d
gg
s
ith
ith
D
Ed
C
A
le
oa
w
w
d
l
e/
e
fy
ru
n
e
e
i
at
at
oa
ar
ar
od
ow
pl
re
re
LS
C
C
M
U
D
Sh
Sh
R

Can Share with All
N

Applies to non-owners only.
Any tables.
Author of at least one table in relationship.
Only when read permission for columns used in the relationship.
With edit permission.

None

Table notes:
1.
2.
3.
4.
5.

Page 167

ThoughtSpot Administration Guide

Data security

December 09, 2017

Security model ffor
or sharing objects
You can share with groups and with individual users. Sharing of tables can be defined at the table, column,
or row level. This provides flexibility in modeling your data security policy. Security and sharing settings
apply to several different types of objects, each of which has its own security default settings and rules.
Object
type

Description

Def
Default
ault security model

Tables

The source data tables
that have been loaded
using ThoughtSpot
Loader.

Administrator users have access to source tables. They can
share a table with other users or groups. See Share tables
and columns

Columns

The columns in the
source data tables that
have been loaded using
ThoughtSpot Loader.

Administrator users have access to columns in the source
tables. They can share selected columns with other users or
groups. See Share tables and columns

Rows

The rows in the source
data tables that have
been loaded using
ThoughtSpot Loader.

All rows in the source tables are shared with all users by default.

Imported
data

Data that was imported
using a Web browser.

Only the user who imported the data (and any user with administrator privileges) has access to it by default. They can
share a table (or selected columns) with other users or
groups. See Share tables and columns

Worksheets

A worksheet created
using a Web browser.

Only the creator of the worksheet (and any user with administrator privileges) has access to it by default. They can
share a worksheet with other users or groups. See Share
worksheets

Pinboards

A pinboard of saved
search results.

Anyone who can view a pinboard can share it. See Share a
pinboard

When you share an object, only the users and groups that have SHAREABLE set for the Sharing visibility
option appear on the dialog.

ThoughtSpot Administration Guide

Page 168

Data security

December 09, 2017

User in groups marked NO
NOT
T SHAREABLE cannot share objects among themselves. In multi-tenant
scenarios, admins can create groups that bring together portions of two non-share groups so that they
can share. For example, the members of group C can share even if they belong to other groups that
cannot.

Only users in the Adminis
dministr
tra
ators group can share with groups marked as NO
NOT
T SHAREABLE
SHAREABLE.

Row le
lev
vel security
ThoughtSpot includes robust row level security, which allows you to filter all objects users see based on
conditions you set at the level of row values in base data tables.
You may find it useful to create groups for RLS. To prevent these groups from appearing in the Shar
Share
e
dialog, create a NO
NOT
T SHAREABLE group with a single user and an RLS group with another single user
(1-to-1).

Rela
elatted inf
informa
ormation
tion
• Revoke access (unshare)
• Row level security

ThoughtSpot Administration Guide

Page 169

Share tables and columns

December 09, 2017

Shar
Share
e tables and c
columns
olumns
Summary: You can share an entire table, or only some of its columns.
By default, when data is loaded using the ThoughtSpot Loader, ODBC, or JDBC, it is only visible to
administrators. Data imported from a Web browser is visible to administrators and the user who uploaded
it. Administrators and owners can share Can V
Vie
iew
w or Can E
Edit
dit privileges on tables with other users, who
can further share them with others.
Use caution when sharing tables, because any objects created from them will have dependencies on the
tables and their underlying structure. Objects created from tables can include worksheets, answers, and
pinboards. This means that if a user wants to drop or modify a table, any object that depends upon it
must be edited or removed first, to remove the dependency. For this reason, it is a best practice to only
grant the Edit permission on tables to a small number of users.
Share a table or imported data by following these steps:
1. Click on the DATA icon in the top navigation bar.
2. Click on Tables
ables.

3. Select one or more tables to share, and click the Shar
Share
e icon.

4. Select Entir
Entire
eT
Table
able or Specific C
Columns
olumns.

ThoughtSpot Administration Guide

Page 170

Share tables and columns

December 09, 2017

5. If you selected Specific C
Columns
olumns, select the column to share.
6. Click + and select the users and groups that you want to share with.
7. Configure the level of access by selecting from the dropdown list. You can select:
• Can V
Vie
iew
w to provide read-only access. This enables viewing the table data and
defining worksheets on the table.
• Can E
Edit
dit to allow modification. This enables renaming, modifying, or deleting the
entire table and adding or removing its columns.
8. Click Add and Sa
Sav
ve.
9. Click Done
Done.

ThoughtSpot Administration Guide

Page 171

Share worksheets

December 09, 2017

Shar
Share
ew
worksheets
orksheets
Summary: You can share worksheets with users or with groups.
Sharing a worksheet allows users to select it as a data source and
search it.
When you share a worksheet, all of its columns are shared. Sharing a worksheet does not share the
underlying tables. If you want to share the underlying tables, see Share tables and columns. A worksheet
can be shared by the owner of the worksheet, or by an administrator. Users can start searching a
worksheet as soon as the worksheet is shared with them.
To share a pinboard:
1. Click on the DATA icon on the top navigation bar and then on Worksheets
orksheets.

2. Select one or more worksheets to share, and click the Shar
Share
e icon.

3. Click + A
Add
dd users or gr
groups
oups and select users or groups that you want to share with.

ThoughtSpot Administration Guide

Page 172

Share worksheets

December 09, 2017

4. Configure the level of access by selecting from the dropdown list. You can select:
• Can V
Vie
iew
w to provide read-only access. Enables viewing the worksheet and searching
on it.
• Can E
Edit
dit to allow modification. Enables renaming, modifying filters, or deleting the
worksheet and adding or removing its columns. To add columns to a worksheet a user
needs access to the underlying table.
5. Click Add and Sa
Sav
ve.
6. Click Done
Done.

ThoughtSpot Administration Guide

Page 173

Share a pinboard

December 09, 2017

Shar
Share
e a pinboar
pinboard
d
Summary: Whenever you view a pinboard you have the option of
sharing it with others.
When you share a pinboard what you are really sharing is a live link to the pinboard, when you click Shar
Share
e
with…
with…. So whenever someone else views it, they will see the most recently saved version with the most
recent data. You do not have to be an administrator or the owner to share saved pinboards. Any user can
share them, based on the access levels the user has.
To share a pinboard:
1. Configure the pinboard to look as you’ll want it to appear when shared.
2. Click the Shar
Share
e icon.

3. Click + A
Add
dd users or gr
groups
oups and select users or groups that you want to share with.

ThoughtSpot Administration Guide

Page 174

Share a pinboard

December 09, 2017

4. Configure the level of access by selecting from the dropdown list. You will only see options
available, based on your own access level. For example, if you have only Vie
iew
w access, you cannot
share as Edit
dit. You can select:
• Can V
Vie
iew
w to provide read-only access. If the person doesn’t have access to the
underlying data, they can only view a shared pinboard. If they change anything on the
pinboard, their changes are not saved. In order to persist the changes, the user would
need to make a copy of the modified pinboard.
• Can E
Edit
dit to allow modification. Enables renaming or deleting the shared pinboard. If a
person with edit privileges modifies a shared pinboard, their changes will be saved to
it.
5. Click Add and Sa
Sav
ve.
6. Click Add P
Permis
ermissions
sions.

ThoughtSpot Administration Guide

Page 175

Security for SpotIQ functions

December 09, 2017

Security ffor
or SpotIQ functions
SpotIQ is a feature in ThoughtSpot that automatically generates insights into system data. The feature
works on all the data in your system, search queries, saved answers, and pinboards. Because SpotIQ uses
the same data security model as other data in the system, there is no need to build a new schema or
security model to support it.
SpotIQ automatically generates insights into data when a user requests them. These requests can be run
immediately or users can schedule regular analysis. SpotIQ requests for insights can put additional load on
your system depending on the amount of data being analyzed and how frequently users make use of it.
Users are required to have the Has Spot IQ privilege to use this feature. Users without this privilege cannot
view insights unless the users that generated the insights add them to a pinboard and share the pinboard
with others.
You may want to restrict access to a subset of your users or even to a subset of your managers. To restrict
access to this feature:
1. Create a group called SpotIQUsers
SpotIQUsers.
2. Grant this group Has Spot IQ privilege
privilege.
3. Enable users to this group.

ThoughtSpot Administration Guide

Page 176

Revoke access (unshare)

December 09, 2017

Revok
oke
e ac
acc
ces
esss (unshar
(unshare
e)
You may need to revoke access to an object (table, worksheet, or pinboard) that you have previously
shared. Unsharing an object is very similar to sharing it.
To unshare one or more objects:
1. Go to the area where the object(s) you want to unshare is located. From the top menu bar:
• If the object is a table or worksheet, click DATA.
• If the object is a pinboard, click Pinboar
Pinboards
ds.
• If the object is an answer, click Ans
Answ
wers
ers.
2. Find the object(s) in the list, and check the corresponding box(es).
3. Click the Shar
Share
e icon.

4. Click the X next to the users and groups that you want to remove from sharing.

ThoughtSpot Administration Guide

Page 177

Revoke access (unshare)

December 09, 2017

5. Click Done
Done.

ThoughtSpot Administration Guide

Page 178

Row level security (RLS)

December 09, 2017

Row le
lev
vel security (RLS)
Summary: Using row level security, you can effectively customize
search results and pinboards for each group that views them.
Row level security (RLS) allows you to define which groups can see individual rows in a table, based on
the values in one of its columns. This RLS feature can handle thousands of groups, and allows you to set
up flexible rules that are self-maintaining.

Ho
How
w RLS w
works
orks
RLS works at the group level, not the individual user level. By default, all groups can see all rows for any
table they can view. You can limit the rows a group can see by setting conditions on column values. The
row level security rules you define on a table also apply to any worksheets and pinboards based on that
table.
There are several reasons you might want to use row level security:
Reason

Ex
Example
ample

Hide sensitive data from groups who
should not see it.

In a report with customer details, hide potential customers (those who have not yet completed their purchase) from everyone except the sales group.

Filter tables to reduce their size, so that
only the relevant data is visible.

Reduce the number of rows that appear in a very large
table of baseball players, so that players who are no
longer active are not shown except to historians.

Enable creation of a single pinboard or visualization, which can display different
data depending on the group who is accessing it.

Create one sales pinboard that shows only the sales in
the region of the person who views it. This effectively
creates a personalized pinboard, depending on the viewer’s region.

RLS and adminis
administr
tra
ators
If your installation has enabled the Can A
Adminis
dministter RLS privilege, user groups with this privilege (directly
or indirectly) can bypass row-level security (RLS) rules on worksheets. This privilege can only be assigned
by a user who already Has adminis
administr
tra
ation privilege
privilege. See “Change inclusion, join, or RLS for a worksheet for
more information on how to do this.
Users with Has adminis
administr
tra
ation privilege are administrators and can see can see all data sources, and no
type of row level security applies to them.

ThoughtSpot Administration Guide

Page 179

How rule-based RLS works

December 09, 2017

Ho
How
w rule-based RLS w
works
orks
Summary: Use rule-based RLS to protect your data so that users see
only those rows they are allowed to see based on their group
membership.
Row level security works at the group level, not the individual user level. By default, all groups can see all
rows for any table they can view. You can limit the rows a group can see by setting rules based on the
data values contained in one or more columns. The row level security rules you define on a table also
apply to any worksheets and pinboards based on that table.
For each data source (table or imported data), you will define one or more rules that govern which groups
can see which data. The rules take the form of an expression which is evaluated for each row and group
combination, to decide if that group can see that row. If the expression evaluates to “true”, for a particular
group, they will be able to see that row.
For a list of operators and functions you can use to build these expressions see Row level security rules
reference.

Bes
Bestt pr
practic
actices
es ffor
or using Rule-Based R
Ro
ow L
Le
evel
Security
Use these best practices for Rule-Based Row Level Security:
1. Contact ThoughtSpot Support to have them disable search suggestions based on data values.
These are not hidden from users when you set row level security, so if you don’t want them to
ever see a search suggestion from a row they are not allowed to see, you’ll need to disable the
data value search suggestions.
2. Set up row level security on every table to which it applies.
It is always a possibility that a particular search will only include data from a single table, and a
user will see something they shouldn’t. So protect your data by setting row level security
wherever you want to keep data secure.
3. Give users access to worksheets instead of tables.
This is a general best practice in all implementations. It makes things easier for end users,
because they only need to choose among a few sources, rather than every table. Also they won’t
have to choose five separate tables to get meaningful results. They can choose the single
worksheet that combines the tables.
4. Explicitly grant access for users that should see all rows.
As soon as you create a row level security definition on a table for one group, all other groups
are then blocked from seeing any rows in the table. You have to specifically grant other groups
access in order for them to see any rows.
If you want to ensure that a group can always see all rows in a table, use a rule that always
evaluates to “true” for that group. For example:
• if ts_groups = supergroup then true

ThoughtSpot Administration Guide

Page 180

How rule-based RLS works

December 09, 2017

Row le
lev
vel security with multiple c
conditions
onditions
When multiple row level security rules apply, the permissions are additive. That is, when there are multiple
row level security conditions specified on a table, they are applied using an OR operator. If any of the rules
applied allow a user to see a particular row, the row will be shown to that user.
If a user is a member of multiple groups, the user will be able to see all the rows that are visible to all of
the groups, so the most permissive policy is used.

ThoughtSpot Administration Guide

Page 181

Set Rule-Based RLS

December 09, 2017

Set Rule-Based RLS
Summary: Explains the process for setting RLS rules.
Setting row level security is a three steps process:
1. Disable data value suggestions
2. Access the Rule Builder.
3. Define Rule-Based Row Level Security rules.

Disable da
data
ta v
value
alue sugges
suggestions
tions
When you set Rule-Based Row Level Security, you need to first turn off search suggestions on data values.
When Rule-Based Row Level Security is set, it protects users from seeing data they shouldn’t in
worksheets and pinboards. However, the search suggestions are not filtered using Rule-Based Row Level
Security, so it is possible someone could see a data value they should not in a search suggestion. Disabling
suggestions on data values corrects this. Be sure and do this procedure before setting up Rule-Based Row
Level Security.
Contact ThoughtSpot Support, and tell them that you will be setting up Rule-Based Row Level Security.
Ask them to disable data value suggestions for you. When this setting has been made, continue with the
next procedure.

Acces
esss the Rule Builder
To set up rule-based row level security, you first need to access the Rule Builder. To get to the Rule Builder:
1. Click on DATA, on the top navigation bar.

2. Select a table from the list by clicking on it.
Row level security can only be set on tables and imported data, not on worksheets. The settings
you make to the tables automatically apply to any worksheets or pinboards created on top of
them.
3. Click Row security at the top right side of the page.
4. Click the + A
Add
dd rro
ow security button.

ThoughtSpot Administration Guide

Page 182

Set Rule-Based RLS

December 09, 2017

5. The Rule Builder will appear, where you can define row level security rules.

Define Rule-Based R
Ro
ow L
Le
evel Security rules
You define row level security by creating an expression that gets evaluated for every row and group
combination. This powerful feature can be used with up to thousands of groups. To define a row level
security rule:
1. Open the Rule Builder.
2. Use the Rule Builder window to enter a row security rule.
You’ll type in an expression, which gets e
valuated for every row and group combination.
If the rule evaluates to true for a particular row and group, that group will be able to see that

ThoughtSpot Administration Guide

Page 183

Set Rule-Based RLS

December 09, 2017

row. Use the variable ts_gr
ts_groups
oups to refer to the group name. For example, the expression
ts_groups = location would allow users to only see rows where the value in the location
column was the same as their group name.
Notice how this type of security rule is self-maintaining. If you were to later add additional
locations, the rule will still work, as long as users are placed in the group that matches their
location.

3. Use formulas if you want to define more complex expressions.
You can see a list of available operators by clicking on Rule As
Assis
sistant
tant.

4. Use the suggestions to build a valid expression.
When the expression is valid, you’ll see a green indicator at the bottom of the Rule Builder. As
you type, you’ll see suggestions for formula syntax, variables, and column names. Using these
suggestions can make defining an expression easier, particularly when it comes to specific
syntax, like enclosing parameters in parenthesis. And if you can’t remember the exact column

ThoughtSpot Administration Guide

Page 184

Set Rule-Based RLS

December 09, 2017

name or variable you want to use, the suggestions can help.
5. Click Sa
Sav
ve.
The rule you created will be shown in the list of rules.
6. Click on its name to view or edit the rule. You can also add more rules by clicking + A
Add
dd.
To test your rule, create a search that includes the column(s) you used in your expression, save it to a
pinboard, and share it with all users. Log in as users in different groups, and make sure they are seeing the
appropriate rows in the pinboard you created.

Bypas
ypasss RLS on a w
worksheet
orksheet
Administrators can bypass the RLS rules set on a the table at the worksheet level. Bypassing the
underlying RLS rules allows users, that would not otherwise be unable, to see an aggregate/market view
of a tables data. See how to “Change inclusion, join, or RLS for a worksheet in this documentation for
more information.

ThoughtSpot Administration Guide

Page 185

System administration

December 09, 2017

System adminis
administr
tra
ation
System administration includes applying upgrades, backing up and restoring the cluster, snapshotting, and
adding or removing nodes.

Adminis
dministr
tra
ation ttools
ools
Use these tools to perform administrative actions:
• tscli: an administrative command line interface.
• tsload: a command for loading data directly into the database.
• TQL: a command line SQL interface to interact with databases.

ThoughtSpot Administration Guide

Page 186

System monitoring

December 09, 2017

System monit
monitoring
oring
System monitoring tools in ThoughtSpot include the Control Center, system log files and out-of-the-box
system monitoring pinboards.

System Health C
Cent
enter
er
The ThoughtSpot application includes a System Health Center, for easy monitoring of usage and cluster
health, including alerts. You can view the System Health Center by clicking on the Admin icon and then
clicking System Health
Health.

Overview
The Ov
Overvie
erview
w tab shows a summary of overall cluster status, usage and capacity information,
configuration changes, and critical alerts.

ThoughtSpot Administration Guide

Page 187

System monitoring

December 09, 2017

Data
The DATA section shows all the stored tables with details on the last update time, time taken for autoindexing, number of rows, etc.
The Da
Database
tabase section has the following values:
Section

Sta
tatus
tus

Database

READY

Meaning
The data has been loaded.

IN PROGRESS

The data is still being loaded.

STALE

The data is not up to date.

ERROR

The table is invalid. Call Customer Support.

Search

The data is up to date and searchable.
READY

The data is not ready to be searched.
NOT READY

DELETING INDEX

The table has already been deleted, but the index still exists
due to the latency between the database and search engine.

INDEXING DISABLED

Either too many tokens exist in a column for it to be in-

ThoughtSpot Administration Guide

Page 188

System monitoring

Section

Sta
tatus
tus

December 09, 2017

Meaning
dexed, or indexing has been disabled manually.

CREATING INDEX

The index is being created.

UPDATING INDEX

A change has been made to indexing or the data, and the
index is being updated to reflect it.

Cluster Manager
The Clus
Clustter Manager section show detailed information about a cluster including latency over time,
snapshot status, installed release, node functions, and logs.

ThoughtSpot Administration Guide

Page 189

System monitoring

December 09, 2017

Events and Alerts
The Events and Alerts section shows notifications, alerts, and an audit trail of cluster configuration
changes..

System monit
monitoring
oring pinboar
pinboards
ds
There are several system monitoring pinboards in ThoughtSpot that include information about the system

ThoughtSpot Administration Guide

Page 190

System monitoring

December 09, 2017

status and resource usage. The information in these pinboard is updated hourly from an internal database
that collects monitoring statistics.

The monitoring pinboards can only be viewed by users with the administrator privilege. They are based on
worksheets, which administrators can view, but not modify. The underlying tables are protected system
tables that cannot be accessed directly. However, you can create new monitoring reports from the
worksheets.
The worksheets for system monitoring are:
•
•
•
•
•

Ts:
Ts:
Ts:
Ts:
Ts:

bi server
database
loader
search
service resources

Here is a list of the system monitoring pinboards:
• TS S
Sta
tats:
ts: Usage Helps you see how much the system is being used. Shows search and pinboard
activity by user and by date. Examples include:
◦ Questions asked by user
◦ Questions asked by date
◦ Pinboard impressions
• TS S
Sta
tats:
ts: Sugges
Suggestions
tions Helps you monitor the performance statistics for the suggestions
provided in the search bar. Shows the number and latency of suggestions given over time.
Examples include:
◦ Suggestion volume over time
◦ Suggestion latency over time
• TS S
Sta
tats:
ts: Queries Helps you monitor database performance over time by showing query volume,

ThoughtSpot Administration Guide

Page 191

System monitoring

December 09, 2017

latency, and any errors. Examples include:
◦ Query latency by size of response
◦ Average vs. maximum query latency
◦ Database queries and errors
• TS S
Sta
tats:
ts: R
Resour
esourc
ce Usage Helps you monitor cluster resources by showing memory and CPU
usage per component:
◦ Service
◦ Database
◦ Search
◦ Host
◦ Aggregate (all)
Examples include:
◦ CPU usage per component over time
◦ Memory usage per component over time
◦ Aggregate memory usage over time

Log files
Many of the administration commands output logging information to log files. The logs get written into
the fixed directory /export/logs, with a sub-directory for each subsystem. The individual log directories
are:
•
•
•
•

/export/logs/orion
/export/logs/oreo
/export/logs/hadoop
/export/logs/zookeeper

System monit
monitoring
oring notifica
notifications
tions
You can configure ThoughtSpot to send emails to addresses you specify with monitoring reports and a
cluster heartbeat. Follow these steps to Set up monitoring.

ThoughtSpot Administration Guide

Page 192

About the Space Utilization chart

December 09, 2017

About the Spac
Space
e Utiliza
Utilization
tion chart
The Space Utilization chart is one of the available charts for you to use when checking the cluster
overview. You can find the chart in the Ov
Overvie
erview
w section of the System Health center. This line chart
displays the total used space, which consists of raw uncompressed data, including replication.

The x-axis is by time. It allows you to zoom in and see daily or hourly data. The y-axis measures the size in
GB. So in the Space Utilization chart above, the green line shows the amount of capacity in use in the
system, while the red line shows the total capacity. The increase in the red line at the end of the period
indicates the addition of extra hardware, resulting in increased capacity.

ThoughtSpot Administration Guide

Page 193

Send logs when reporting problems

December 09, 2017

Send logs when rreporting
eporting pr
problems
oblems
You can generate a log bundle which you can then send to ThoughtSpot Support or you can send logs
direct to your administrator.

Gener
Genera
ate log bundle
Before you can send a log bundle to ThoughtSpot Support, you must Connect to the ThoughtSpot
Support file server. This is a one-time setup operation.
To generate a log bundle:
1. Log in to the Linux shell using SSH.
2. Issue the command to generate the log bundle:
tscli callhome generate-bundle
--d  --since 
Not
Note:
e: Don’t forget to include d after your specified number of days. For example, 30d.
3. Change directories to the directory where you wrote the log bundle.
4. Issue the command to send the log bundle to ThoughtSpot Support:
tscli fileserver upload
--file_name 
--server_dir_path 

Send a log tto
o the adminis
administr
tra
ator
Alternately, you can easily send log files directly to your administrator with a single click. When
ThoughtSpot encounters a problem, a red bar displays in the browser with an error message. You can use
the Report Pr
Problem
oblem option to complete this task.
1. Click Report Pr
Problem
oblem in the bottom right corner of the error message.

The logs will be sent to your administrator as an email attachment from your email account.

ThoughtSpot Administration Guide

Page 194

Send logs when reporting problems

December 09, 2017

Your administrator then has the option to followup with ThoughtSpot, if necessary.

ThoughtSpot Administration Guide

Page 195

Set up recording for Replay Search

December 09, 2017

Set up rrec
ecor
ording
ding ffor
or R
Repla
eplay
y Sear
Search
ch
Summary: You can use the recording to create training for your users
on how to search your own data.
Recording a search replay requires administrator privileges and a Firefox browser. You must override some
of your browser security settings in order to use the ThoughtSpot application to make the recording. This
is a one time setup operation. If you do not wish to do this, you can replay the search and record it using
QuickTime, Camtasia, or another screen cam recording tool.
To record a search replay using ThoughtSpot:
1. While viewing a chart or table in ThoughtSpot, click the Repla
eplay
y Sear
Search
ch icon.

2. Click the Rec
ecor
ord
dR
Repla
eplay
y button.
If you do not see the button, you must log in as a user with administrator privileges.

ThoughtSpot Administration Guide

Page 196

Set up recording for Replay Search

December 09, 2017

A message will display, showing a URL and a domain or an IP address.
3. Make note of both of these items.
4. Open a new browser tab and go to the URL shown in the message ( for example,
“about:config”).
Depending on which browser and version you are using, you may need to access the browser
configurations through a menu or by typing in a different URL. Check your own browser help
section for information on how to access the browser configuration settings, if necessary.

You may see a message warning that you are about to override the browser settings.
5. If you trust yourself, click “I’ll be careful, I promise!”.

ThoughtSpot Administration Guide

Page 197

Set up recording for Replay Search

December 09, 2017

6. Find the setting for media.
media.getusermedia.scr
getusermedia.screensharing.allo
eensharing.allow
wed_domains
ed_domains, and add the domain
used by ThoughtSpot.
This domain will be the same one you made note of from the Cannot rrec
ecor
ord
d scr
screen
een message.

7. If you see a message asking if you’d like to share your screen with the IP address or domain
name of ThoughtSpot, select Entir
Entire
e scr
screen
een.

8. When the search replay has been recorded, you’ll see a confirmation. Select Do
Download
wnload.

ThoughtSpot Administration Guide

Page 198

Set up recording for Replay Search

December 09, 2017

9. Save the recording on your computer by selecting Sa
Sav
ve File and clicking OK
OK.

ThoughtSpot Administration Guide

Page 199

Understand the backup strategies

December 09, 2017

Unders
Understand
tand the back
backup
up sstr
tra
ategies
This section discusses three strategies for backing up your ThoughtSpot cluster.

Snapshots
A snapshot is a point-in-time image of your running cluster. Snapshots are both taken on and restored to a
cluster while it is running. Each cluster has a enabled by default a snapshot configuration. This
configuration instructs the system to periodically take snapshots. Creation of a snapshot takes about 20
seconds. Once taken, a snapshot is persisted on disk in the cluster’s HDFS.
You can also create a snapshot manually. You should create a snapshot before making any changes to the
environment, loading a large amount of new data, or changing the structure of a table. A snapshot may
only be restored to the same cluster on which it was taken. The cluster software release version must
match the snapshot release version.
If you need to move data between clusters or restore to a cluster that was updated to a new release,
contact ThoughtSpot Support.

Back
Backups
ups
A backup is a procedure that stores a snapshot outside of a ThoughtSpot cluster. Backups are stored in a
directory on a local or network file system. You can store all of the data associated with a snapshot or a
portion of that data or only metadata. There is no default configuration enabled for backing up a cluster.
You can configure on yourself or you can take backups manually. Backing up periodically protects your
company from losing data and/or user work.
You can use a backup to restore a cluster to a prior state, a differently configured appliance, or move the
backup from an appliance to a virtual cluster or vice versa.

Offline back
backup
up clus
clustter
The most robust strategy for backup and recovery requires having a backup cluster offline that is kept in
sync with the production cluster. Then, if the production cluster fails, the backup cluster can be drafted to
take its place with minimal loss of work and disruption to operations.
Details on this architecture and instructions on setting it up are available in the ThoughtSpot Disaster
Recovery Guide, which you can request from ThoughtSpot.

Choosing when tto
o use a sstr
tra
ategy
Depending on your situation and your goals, you can choose to use a snapshot or a backup. This table
should help you decide:
Snapshot
Used tto
o

To restore to a cluster to particular point
in time.

ThoughtSpot Administration Guide

Back
Backup
up

• Restore a cluster to a prior

Page 200

Understand the backup strategies

December 09, 2017

state.
• Move a cluster to a different
HW appliance.
• Move a cluster to VM appliance.
• Removal of a node.
• Restoring to a cluster running
a different release from the
one where the backup was
taken.

Stor
ored
ed

In the cluster's HDFS

Outside the cluster on either local or
NAS disk.

Adv
dvantages
antages
• Can be taken on or restored to
a running cluster
• Creation and restore is fast

• Very stable medium.
• Can be used to recover from
data loss or corruption, even if
your cluster was destroyed.
• Can be typed as full, lightweight, or dataless.

• Includes all data, state, and
metadata etc. created between
snapshot creation and restore.
• Are lost if the HDFS name
node fails, you lose multiple
disks at once, or the entire
cluster is destroyed
• Can only restored to the cluster they were taken from

• Backups require deleting the
existing cluster first.
• You are resonsible for validating your backup configuration
as viable for restoring a cluster.
• Best practice recommends you
to maintain multiple backups.
• Are typically large in size.
    You
should never restore from a
snapshot or backup yourself,
instead contact ThoughtSpot
Support for help.

Limita
Limitations
tions

ThoughtSpot Administration Guide

Page 201

Understand backup/snapshot schedules

December 09, 2017

Unders
Understand
tand back
backup/snapshot
up/snapshot schedules
Summary: Explains how schedules and gives examples.
You can schedule periodic snapshots and backups. For snapshots, ThoughtSpot comes configured with a
strongly recommended periodic backup policy. For backups, there is no such policy but you may want to
create one or several of your own configurations. This section is useful for understanding how to
understand existing schedules and how to configure new schedules.

Configur
onfigura
ation fforma
ormatt
ThoughtSpot uses a protocol buffer configuration file to hold snapshot and backup policies. There are
slight differences between the configuration of snapshots and backups. You’ll read more about these later.
However, the file format defines a schedule structure which is the same for both snapshots and backups.
The following example shows the schedule format:
schedule {
period {
number: integer
unit: MINUTE | HOUR | DAY
}
retention_policy {
bucket {
time {
number: integer
unit: MINUTE | HOUR | DAY
}
capacity: integer
}
}
offset_minutes_from_sunday_midnight: integer
}

The schedule has the following components:
period

Specifies the frequency in the chosen unit. You can
specify the unit as MINUTE, HOUR, or DAY.

retention_policy

Specifies retention intervals. Retention is on a first-infirst-out (FIFO) basis. So, the oldest result is always discarded. You can specify the unit as MINUTE, HOUR, or
DAY. You can specify multiple retention buckets and they
can have different retention policies.

offset_minutes_from_sunday_midnight

Determines the minute within the hour you’d like execution to start. Setting this to zero is equivalent to midnight.

ThoughtSpot Administration Guide

Page 202

Understand backup/snapshot schedules

December 09, 2017

Work thr
through
ough an e
ex
xample schedule
In this section, you work through an example schedule. This is a working example that is the actual default
snapshot schedule set on every ThoughtSpot instance.
schedule {
period {
number: 1
unit: HOUR
}
retention_policy {
bucket {
time {
number: 1
unit: HOUR
}
capacity: 3
}
bucket {
time {
number: 4
unit: HOUR
}
capacity: 2
}
}
offset_minutes_from_sunday_midnight: 0
}

Under this policy, a snapshot is taken every hour starting at midnight. You can see that by combining the
period of 1 (one) hour with the midnight offset of 0 (zero).
schedule {
period {
number: 1
unit: HOUR
}
...
}
offset_minutes_from_sunday_midnight: 0
}

Using this frequency, a total of 24 snapshots are taken in a day.
1

2

3

4

5

6

7

8

9

10

11

12

13

14

…

24

If you were to specify a number of 2, the frequency changes. The first execution would start at midnight
but subsequent executions would happen every 2 hours as shown here:
2

4

6

8

10

12

14

…

24

You use the retention_policy to control how many snapshots are kept. In this example, the first bucket

ThoughtSpot Administration Guide

Page 203

Understand backup/snapshot schedules

December 09, 2017

retains a snapshot every three hours.
retention_policy {
bucket {
time {
number: 1
unit: HOUR
}
capacity: 3
}
...
}

When the fourth hour comes along, the snapshot from first hour is discarded as per FIFO behavior. So in
the 4th hour, you’ll have the snapshots from hours 2, 3, and 4 in this retention bucket.
1D

2R

3R

4R

5

6

7

8

9

10

11

12

13

14

…

24

The second bucket retains the snapshot taken at four hour intervals.
retention_policy {
...
bucket {
time {
number: 4
unit: HOUR
}
capacity: 2
}
}

It retains two of these four-hour-interval snapshots at any one time. By hour 9 during the day, you have
the snapshots from hour 4 and hour 8 in this second bucket.
1

2

3

4R

5

6

7

8R

9

10

11

12

13

14

…

24

Consider what you will have in the first bucket in hour 9? The first bucket will have the snapshots from
hour 9, 8, and 7.
At the end of the day, in the first bucket, you will have 22, 23, and 24th snapshot. While in the second
bucket, you will have the 20th hour and the 24th hour snapshots.
1

…

12

13

14

15

16

17

18

19

20R

21

22R

23R

24R

What if you changed the period frequency to every 2 hours? What would you have retained in your
buckets at hour 24?
1

…

12

14

16

18R

20R

22R

24R

As you can see, when defining a policy it can be helpful to graphically represent the frequency you
configure. Then, determine which time blocks are important to retain before determining your retention
bucket.

ThoughtSpot Administration Guide

Page 204

Work with snapshots

December 09, 2017

Work with snapshots
Summary: A snapshot is a point-in-time image of your running cluster
you can use to restore the cluster back to a specific point in time.
In this section, you learn how to work with the default snapshot configuration that is enabled on ever
cluster and how to take manual snapshots of your own.

Cr
Crea
eatte a manual snapshot
You should create a snapshot before making any changes to the environment, loading a large amount of
new data, or changing the structure of a table. You can have up to 20 manual snapshots at a time, after
which, you have to clear one before you are able to create another. If you need to delete a snapshot,
contact ThoughtSpot Support.
 Not
Note:
e: When you upgrade, all existing snapshots from the previous version of ThoughtSpot will become
manual snapshots.
Taking a snapshot is fast, about 20 seconds. It happens invisibly in the background of a running cluster. If
you would like to restore from a snapshot instead, contact ThoughtSpot Support.
To create a snapshot:
1. Log in to the Linux shell using SSH.
2. Initiate a snapshot, providing a name and reason for creating it: Snapshot names must be 44
characters or less.
$ tscli snapshot create  
3. Check that the snapshot was created:
$ tscli snapshot ls

Configur
onfigure
e periodic snapshots
By default, each ThoughtSpot cluster is configured to take automatic, periodic snapshots of your cluster.
This section explains how to learn more about the periodic snapshots in your cluster.
The default snapshot policy is enabled for every cluster. You can use the tscli snapshot-policy show
command to display the current policy for periodic snapshots.
$ tscli snapshot-policy show
schedule {
period {
number: 1
unit: HOUR
}
retention_policy {
bucket {
time {
number: 1

ThoughtSpot Administration Guide

Page 205

Work with snapshots

December 09, 2017

unit: HOUR
}
capacity: 3
}
bucket {
time {
number: 4
unit: HOUR
}
capacity: 2
}
}
offset_minutes_from_sunday_midnight: 0
}
enabled: true

This policy takes a snapshot every hour starting at midnight on Sunday. It retains the snapshots from the
last three hour intervals and two snapshots from two of the previous 4 hour intervals. That means, there
are 5 periodic snapshots retained overall. For detailed information about understanding the schedule, see
Understand backup/snapshot schedules.
You shouldn’t change this default policy unless instructed to by support. If you have to adjust it for some
reason, you can use, tscli snapshot-policy update command. This opens the current policy in an
editor. Your policy should never retain more than 20 snapshots at any point in time. Exceeding this
number can impact cluster performance.
You cannot delete the snapshot policy. However, you can disable the policy by executing thetscli
snapshot-policy disable command. And you can re-enable it by running, tscli snapshot enablepolicy.
CAUTION: Backups rely on the snapshot system. For this reason, you should never disable the periodic
snapshot system. For example, if you have disabled the periodic snapshots and periodic backups are
enabled, then the periodic backup may use a very outdated snapshot or it may fail all together.
To check your current periodic snapshot policy:
1. Log in to the Linux shell using SSH.
2. Enter tscli snapshot-policy show to view the policy.

ThoughtSpot Administration Guide

Page 206

Understand backup modes

December 09, 2017

Unders
Understand
tand back
backup
up modes
A backup is a procedure that stores a snapshot outside of a ThoughtSpot cluster. You can use a backup to
restore a cluster to a prior state, a differently configured appliance, or move it to from an appliance to a
virtual cluster or vice versa. Other advanced administrative operations also use backups.
You can create a manual backup or configure an automated, periodic backup A backup stores snapshot
outside of a ThoughtSpot cluster. For manual backups, the system creates a backup using the named
snapshot you specify. For periodic backups, the system uses the most recent snapshot to create the
backup.
 Warning: You should never disable the periodic snapshot system as backups rely on it. For example, if
you have disabled the periodic snapshots system and periodic backups are enabled, then the periodic
backup may use a very outdated snapshot or it may fail all together.
Backups are usually stored on a NAS (network attached storage) file system but you can store them on a
local disk as well. When creating a backup, ThoughtSpot copies a release tarball and several supporting
files to a disk you specify. Storing these supporting files takes about 10 GB of extra space beyond the
backup itself. The final backup image is smaller because these extra files are removed after the backup
completes successfully. So, make sure you have enough disk space both to take a backup and store the
result. Use the tscli storage df command to identify the amount of space available.
You can create a backup using one of three modes, full, lightweight or dataless.

Full back
backups
ups
Full backups are entire backups of the cluster with all data, whether loaded from the web interface or from
tsload. This is the best mode for restoring a cluster and all your data. Once a FULL backup is created, you
can move them between clusters, even if the cluster configuration is different. Full backups can be as large
as 20 GB in addition to the 5 GB of additional files. Some installations can exceed these limits, this is why
it is important to test your backup configuration.
Before creating a manual backup or configuring automated backups, make sure there is enough disk
space on the target disk. Consider an example, where you want to store three backups. If the backup itself
takes 18GB, you need about 18 + 5 = 23 GB of free disk space. Don’t forget that the backup size can grow
over time, so you should occasionally check to ensure you are not in danger of running out of disk space
to store backups.

Lightw
Lightweight
eight back
backups
ups
Lightweight backups contain everything that makes up a cluster so they contain the following:
• Cluster configuration (SSH, LDAP, etc.)
• In-memory data cache
• All data that is stored in HDFS
• Data uploaded by users
• Metadata for the data store
• Users, groups and permissions
• Objects created by users (pinboards, worksheets, and formulas) with their shares and
permissions.
• Data model and row-level security rules.

ThoughtSpot Administration Guide

Page 207

Understand backup modes

December 09, 2017

Data loaded through ThoughtSpot Loader (tsload), ODBC/JDBC drivers, and Data Connect is excluded.
The expectation is that data loaded via tsload is from external sources and so can be re-loaded after the
cluster is restored. An exception is if these mechanisms were used to load data into tables that were first
created through CSV import (that is, a user first loaded the tables via the GUI). In this case, the data, like
the tables they were loaded into, are saved.

Da
Datales
talesss back
backups
ups
A dataless backup saves a backup of the schema (metadata), with no data. Dataless backups allow you to
send a copy of your cluster metadata to ThoughtSpot Support for troubleshooting without compromising
data security and privacy. The size of a dataless backup is usually within 10’s of megabytes provided you
do not have customized binaries.
When restoring from a dataless backup, you must supply the correct release tarball, since this type of
backup does not include the software release.

ThoughtSpot Administration Guide

Page 208

Create a manual backup

December 09, 2017

Cr
Crea
eatte a manual back
backup
up
Use this procedure when you want to manually create a backup. If you would like to restore from a
backup, contact ThoughtSpot Support.
You create a manual backup from an existing snapshot. So, you must identify an existing snapshot to use
or take a new snapshot first. The time required to take a backup depends on the data size. Taking a
backup does not take long, and happens in the background while the cluster is running.
1. Log in to the Linux shell using SSH.
2. Create a manual snapshot or find a snapshot you want to use. To find a snapshot you want to
back up use the following command:
$ tscli snapshot ls
--------------------------------------------------------------------------Name
: pre330
Reason
: pre3.3.0
Hdfs snapshot : pre330
Start
: Wed May 4 18:07:32 2016
End
: Wed May 4 18:08:23 2016
Size(Full)
: 13.24 GB
Size(LW)
: 4.96 GB
Size(Dataless): 39.76 MB
--------------------------------------------------------------------------...
3. Make sure you have enough room on the target disk.
In addition to the size of the snapshot, you will need 10 to 12 GB of disk space. This is because
the process requires space for temporary files. You can use the df command to check disk size.
$ df -h
4. Create the backup, designating the type of backup, the snapshot name, and a directory:
Choose the mode of backup you want to create, either full, lightweight, or dataless. The
destination directory is created for you; do not specify an existing directory. The BASE value is
the name
$ tscli backup create [-h]
[--mode {full|light|dataless}]
[--type {full}]
[--base snapshot_name>]
[--storage_type {local|nas}][--remote]
 
5. Check that the backup was created:
$ tscli backup ls

ThoughtSpot Administration Guide

Page 209

Configure periodic backups

December 09, 2017

Configur
onfigure
e periodic back
backups
ups
You can configure ThoughtSpot to backup automatically at specified times. The policy allows you to
control the type, frequency, retention periods (first-in-first-out), and output location for a periodic backup.
A periodic backup uses the same steps as creating a backup manually. However, you do not need to
specify a snapshot name, the system uses the most recent backup. You can backup to a local file system
or mount a NAS (network attached storage) file system to hold the backup. A NAS is recommended. Make
sure you have adequate space to store the number of backups you want to archive.
The format for a policy includes the following:
name: "name_for_backup"
param {
mode: FULL | DATALESS | LIGHTWEIGHT
type: STANDALONE
}
schedule {
period {
number: integer
unit: MINUTE | HOUR | DAY
}
retention_policy {
time {
number: integer
unit: MINUTE | HOUR | DAY
}
capacity: integer
}
}
offset_minutes_from_sunday_midnight: integer
}
directory: "NAME"
storage_type: NAS | LOCAL
Before creating a policy, make sure you have read Understand backup/snapshot schedules for information
on configuring a schedule element. In addition, you must specify:
Element

Description

mode

The backup mode. FULL backups are necessary for restoring a cluster. See Work with
backups for details on each backup mode.

type

Currently, only STANDALONE is supported.

directory

The location on the disk to place the backup.

storage_type

The type of storage you are using. NAS storage is recommended for FULL backups.

Backups cannot start when another backup is still running. So, choose a reasonable frequency for the
mode in you policy. For example, a FULL backup takes longer than a DATALESS backup. Consider the load
on the system when configuring. Do not backup up when the system would experience a heavy load. For
example, you may want to take FULL backups late in the evening or on weekends.
The retention system deletes the oldest stored backup and the corresponding snapshot on a first-in firstout basis (FIFO). The deletion takes places before the backup that replaces it. This means that if you set a
bucket retention of 1 the system stores a single backup at any one time. And, more importantly, the only
backup would be deleted before the next is taken. For this reason, you should always set the number of

ThoughtSpot Administration Guide

Page 210

Configure periodic backups

December 09, 2017

backups to be greater than 2 (two), to ensure you have at least one backup available in the case of a
failure while taking a backup.
To configure periodic backups:
1. Log in to the Linux shell using SSH.
2. Find a directory with enough disk space to support the retention_policy number you
configure.
You can use df -h to see free disk space and tscli snapshot ls to view existing snapshots
and their size on disk.
3. Use the tscli backup-policy create command.
The command opens a vi editor for you to configure the backup policy.
4. Write and save the file to store your configuration.
By default, newly created policies are automatically enabled. To disable a policy, use the tscli
backup-policy disable command.
5. Verify the policy using the tscli backup periodic-config  command.

Doing mor
more
e with back
backup
up
The following table lists some additional backup commands you can use.
To

Command

List present backup policies.

tscli backup-policy ls

Show a backup policy.

tscli backup-policy show 

Check the status of a policy.

tscli backup-policy status 

Change an existing policy.

tscli backup-policy update 

Disable or enable an existing policy.

tscli backup-policy disable or enable

Delete a policy

tscli backup-policy delete 

Finally, you can time a crontab job with your periodic backup configuration to move a backup to longer
term storage. Simply create a crontab job that moves the backup to a location outside of the directory
defined in the periodic schedule.

ThoughtSpot Administration Guide

Page 211

About restore operations

December 09, 2017

About rres
esttor
ore
e oper
opera
ations
When restoring to a running cluster that where the ThoughtSpot software was not updated, you’ll usually
use a snapshot. But in the case where you’ve updated the cluster to a new release, the configuration has
changed significantly, or you’re restoring to a different cluster, you’ll need to restore from a backup.
Restoring from backup require that you first delete the old cluster. Changes to a cluster that require
restoring from a backup instead of a snapshot include:
• Removal of a node.
• Restoring to a different cluster from the one where the snapshot/backup was taken.
• Restoring to a cluster running a different release from the one where the snapshot/backup was
taken.
You should never restore from a snapshot or backup yourself. To perform a restore from a snapshot or
backup, contact ThoughtSpot Support.

ThoughtSpot Administration Guide

Page 212

About troubleshooting

December 09, 2017

About tr
troubleshooting
oubleshooting
The information here provides very basic troubleshooting. For more detailed troubleshooting, Contact
ThoughtSpot.
• Get logs
For troubleshooting on specific incidents or cluster problems, getting a log bundle can help.
• Netw
Network
ork c
connectivity
onnectivity is
issues
sues
If network connectivity to and from ThoughtSpot is not working, try using these steps to find
and correct the issue.
• Change the time
timez
zone
ThoughtSpot comes configured with the timezone where it is to be installed.
• Br
Bro
owser untrus
untrustted c
connection
onnection err
error
or
If you are not using a SSL certificate for authentication, users will see an untrusted connection
error in their browser when accessing ThoughtSpot. The error looks slightly different depending
upon the Web browser being used.
• Char
Charact
acters
ers not displa
displaying
ying c
corr
orrectly
ectly
Your CSV files are more likely to load smoothly if they are encoded with UTF-8. If you’re having
problems with some characters rendering incorrectly, you can convert the files to UTF-8
encoding before loading the data.
• Clear the br
bro
owser cache
You might occasionally see unexpected behavior that is due to the Web browser caching
information from ThoughtSpot. In this case, clearing the browser cache and reloading the page
should resolve the problem.
• Cannot open a sa
sav
ved ans
answ
wer tha
thatt c
contains
ontains a fformula
ormula
• Da
Data
ta loading ttoo
oo slo
slowly
wly
Some tables may take an unusually long time to load due to a high data version issue. This issue
normally arises when ThoughtSpot completes an upgrade or the system is recovering after a
crash.
• Sear
Search
ch rresults
esults c
contain
ontain ttoo
oo man
many
y blanks
If you find that your search results contain too many blanks when your data source is a
worksheet, there is a simple adjustment you can make to fix this.

ThoughtSpot Administration Guide

Page 213

Get logs

December 09, 2017

Get logs
For troubleshooting on specific incidents or cluster problems, getting a log bundle can help.

Ho
How
w tto
o get logs
There are two ways to get logs:
• When ThoughtSpot encounters a problem, a red bar displays in the browser with an error
message. You can click on Wha
hatt Happened? in the error message for more details. To download
related logs, click Do
Download
wnload T
Trrac
ace
e. Send the logs as an email attachment to the support contact
that is provided. Clicking Report Pr
Problem
oblem will also send the logs as an email attachment to your
administrator.

• You can generate a log bundle using the tscli command tscli logs collect if you are
comfortable with Linux. The command lets you specify which logs to collect and from what time
periods.
Usage for this command is:
tscli logs collect
--include 
[--exclude ]
[--since 
| --from 
--to ]
[--out ]
[--maxsize ]
[--sizeonly]
The full list of all selectors is:
◦ all collects all of the logs listed from the system and the ThoughtSpot application.
◦ system collects all system logs, e.g. syslog, upstart, mail logs, etc.
◦ ts collects all logs from the ThoughtSpot application. This includes falcon, sage, orion
core (cluster management), etc.
◦ orion collects all orion logs including cluster management, hdfs, zookeeper, etc.
Detailed syntax and options are listed in the tscli command reference.

ThoughtSpot Administration Guide

Page 214

Get logs

December 09, 2017

Ex
Examples
amples
Here are some examples of usage for the command tscli logs collect:
To collect all logs from the past day to the default location (/tmp/logs.tar.gz):
$ tscli logs collect --include all --since 1d
In this example, all is a selector for all the available logs.
In most cases, you’ll probably use the selector ts to only capture logs for the ThoughtSpot application:
$ tscli logs collect --include ts --since 2d
For debugging cluster management issues, use a command like this one, which collects logs for system
and orion from the past 2 hours. The output is written to /tmp/debug.tar.gz as specified using --out:
$ tscli logs collect --include system,orion --since 2h --out /tmp/debug.tar.gz
This command collects logs from a specific time window:
$ tscli logs collect --include system,orion --from 20150520-12:00:00 --to
20150522-12:30:00
Advanced usage alert! You can also use --include and --exclude to specify filesystem paths as a glob
pattern. This works like the Linux find(1) command. Pass all the entries in --include starting with / to
find(1), and all entries in --exclude which are not selectors to find(1) using the -not -path flag.
$ tscli logs collect --include system,orion --exclude *hadoop*,*zookeeper* --since 2h
The above command collects all system and all orion logs, but excludes hadoop (hdfs) and zookeeper
logs. See Upload logs to ThoughtSpot Support about using a secure file sever to collect log files or other
files needed for troubleshooting. You can easily send log files to this file serve directly from the
ThoughtSpot instance.

ThoughtSpot Administration Guide

Page 215

Upload logs to ThoughtSpot Support

December 09, 2017

Upload logs tto
oT
ThoughtSpot
houghtSpot Support
ThoughtSpot Support uses a secure file sever to collect log files or other files needed for troubleshooting.
You can easily send log files to this file serve directly from the ThoughtSpot instance.
Before you can upload a file to the secure file server:
1. Configure the connection to the file server.
2. Obtain the directory path on the file server.
The server directory path for uploading a file is formatted like this example: /Shared/
support/. If you do not know the customer name, contact ThoughtSpot Support.
You can upload files directly to the file server using this procedure:
1. Log in to the Linux shell using SSH.
2. Navigate to the directory where the file to be uploaded is located.
3. Issue the command to upload the file, specifying the file name and directory path:
$ tscli fileserver upload --file_name  --server_dir_path 
When your upload succeeds, you will see a confirmation message.

ThoughtSpot Administration Guide

Page 216

Network connectivity issues

December 09, 2017

Netw
Network
ork c
connectivity
onnectivity is
issues
sues
If network connectivity to and from ThoughtSpot is not working, try using these steps to find and correct
the issue.
To troubleshoot network connectivity for ThoughtSpot:
1. Make sure that the network cables are connected correctly.
2. Check that the network cable is connecting the nodes to the network switch.
3. Try replacing the cable with a cable from a known working system to rule out a bad cable or
switch connectivity issues.
4. Make sure the eth0 interface is connected to the network by issuing: ethtool eth0 The port
that’s currently connected will have “link detected” in the last line of the output.
5. If the networking settings have been reconfigured, reboot each of the nodes.

ThoughtSpot Administration Guide

Page 217

Change the timezone

December 09, 2017

Change the time
timez
zone
ThoughtSpot comes configured with the timezone where it is to be installed. Data is imported based on
the timezone of the node from which tsload or tql is run.
If you need to change the timezone, for example when moving a ThoughtSpot appliance to another data
center contact ThoughtSpot Support, and they will change the timezone for you.
Note that if the timezone was not set correctly when shipped, it may be necessary to have ThoughtSpot
Support reset it. This can be true even if the file /etc/timezone lists the correct timezone. Sometimes the
timezone that is listed is not the active timezone and it needs to be reset.

ThoughtSpot Administration Guide

Page 218

Browser untrusted connection error

December 09, 2017

Br
Bro
owser untrus
untrustted c
connection
onnection err
error
or
If you are not using a SSL certificate for authentication, users will see an untrusted connection error in
their browser when accessing ThoughtSpot. The error looks slightly different depending upon the Web
browser being used.
ThoughtSpot uses secure HTTP (the HTTPS protocol) for communication between the browser and
ThoughtSpot. By default there is no SSL certificate for authentication. This must be added by the site
administrator. If the site administrator has not added the certificate, the browser warns the user.
Br
Bro
owser

Warning

Google Chrome

The site’s security certificate is not trusted!

Mozilla Firefox

This Connection is Untrusted

If you see the warning message, choose one of the following options:
• Ask the site administrator to install the certificate.
• Ask the site administrator to turn off SSL using this command in the shell on the ThoughtSpot
instance:
$ tscli ssl off
• You can choose to ignore the message, and access ThoughtSpot without SSL.

ThoughtSpot Administration Guide

Page 219

Characters not displaying correctly

December 09, 2017

Char
Charact
acters
ers not displa
displaying
ying c
corr
orrectly
ectly
Your CSV files are more likely to load smoothly if they are encoded with UTF-8. If you’re having problems
with some characters rendering incorrectly, you can convert the files to UTF-8 encoding before loading
the data.
You might see unexpected characters in your data, especially characters whose ASCII values are at the
high and low end of possible values. Some examples of characters that can appear incorrectly are: æ, ñ, ä,
í, ö.
If this happens, your data will look like this:

Instead of displaying correctly like this:

To encode your data as UTF-8:
1. On Windows, open your CSV file in Notepad. Save the file as CSV with the Unicode option.
2. On Linux or MacOS, issue a command like:
$ iconv -f -t UTF-8 .csv > .csv
3. Reload the data.
4. Attempt to import it again.

ThoughtSpot Administration Guide

Page 220

Clear the browser cache

December 09, 2017

Clear the br
bro
owser cache
You might occasionally see unexpected behavior that is due to the Web browser caching information from
ThoughtSpot. In this case, clearing the browser cache and reloading the page should resolve the problem.
You can usually resolve these situations by clearing the browser cache:
• During a ThoughtSpot session, the browser suddenly displays a white screen and reloading does
not fix the problem. This is due to a self-signed SSL certificate that has timed out during the
session.
• When accessing the Help Center, you see a login screen. This is due to a problem during
automatic authentication in the Help Center, after which the bad login gets cached by the
browser.
To resolve any of these situations, clear the browser cache:
1. Clear the browser cache. This works a little differently on individual browser versions and
operating systems. For example, when using Chrome, to get to the browser cache settings,
navigate to:
chrome://settings/clearBrowserData

2. Click Clear br
bro
owsing da
data
ta. This is the name of the button on Chrome. The name may vary
slightly on other browsers.
3. Reload the page. For example, on Chrome you would click the Reload icon:

ThoughtSpot Administration Guide

Page 221

Clear the browser cache

December 09, 2017

4. Now the problem should be fixed, and the page will appear as expected.

ThoughtSpot Administration Guide

Page 222

Cannot open a saved answer that contains a formula

December 09, 2017

Cannot open a sa
sav
ved ans
answ
wer tha
thatt
contains a fformula
ormula
When working with formulas, keep in mind the data types they return. You may occasionally see
unexpected results, or even be unable to open a saved answer, due to problems with data types and
formulas.
In this scenario, “data type” refers the data type as defined in the column definition when creating the
schema (INT, TIMESTAMP, VARCHAR, etc.).
When you define a formula, both the data type it returns is set automatically. This can lead to problems, if
you build another formula that uses the output of the first formula as input. This can be hard to
understand, so an example will be helpful.
Suppose you have created a worksheet that contains a formula called “weekday” defined as:
day_of_week(date)
The output of that formula is the day of the week (Monday, Tuesday, etc.) returned as a text string
(VARCHAR, ATTRIBUTE).
Then suppose you create an answer using the worksheet as a source. And in the answer, you create
another formula on top of the formula column in the worksheet. This formula is supposed to return the
day of the week that is two days after the given day of the week:
weekday + 2
In this case, you have effectively created a formula on top of another formula. This works fine, so long as
the data types in the worksheet formula can work in the answer formula. If not, you may not be able to
save the answer, or open it once it has been saved. Here, the second formula you created does not work,
because it is invalid. It is trying to subtract a number from a text string.
If you encounter this issue, you will need to open the worksheet and edit its formula so that it returns the
type expected by the formula that was built on top of it. In this case, a numeric data type.
You must change the underlying worksheet column to use day_number_of_week instead of day_of_week.
This is because day_number_of_week returns a numeric data type.
Here are the steps to resolve an issue like this:
1. Open the underlying worksheet that contains the formula whose output data type you need to
change.
2. Click on the formula name to edit the formula.

ThoughtSpot Administration Guide

Page 223

Cannot open a saved answer that contains a formula

December 09, 2017

3. In the Formula Builder, modify the formula, so that it returns the expected data type.
There are data type conversion formulas available to make this easier. To view them and their
syntax, open the Formula As
Assis
sistant
tant, and expand the section called Con
onv
version
ersion.

4. Make your changes, and saving the formula by clicking Sa
Sav
ve.
5. Save the worksheet by clicking Sa
Sav
ve.
6. Now you will be able to open the answer that was created on top of the worksheet.

ThoughtSpot Administration Guide

Page 224

Data loading too slowly

December 09, 2017

Da
Data
ta loading ttoo
oo slo
slowly
wly
Some tables may take an unusually long time to load due to a high data version issue. This issue normally
arises when ThoughtSpot completes an upgrade or the system is recovering after a crash.
The data version is the number of loads that have been historically applied to a table. Every completed
load increments the version number of the table by one. ThoughtSpot would need to process each version
of the table during restoration, which could increase the time it takes to build the table.
There are a few steps you can take to check for a high data version issue and fix it. To improve data
loading speed:
1. Run the following command to find the number of tables that are building and their names
tscli cluster status --mode table
2. You may notice that a few small tables are taking up a lot of time to be built. However, this could
simply be due to the deceivingly large size of the table. There is also the chance it could be due
to a high data version issue. In order to determine if this is a high data version issue, check the
size of the table by running the following command:
echo 'show statistics for server;' | tql
3. If there is a large number of rows in the table, proceed to shard the table.
4. If the table has a small number of rows, then the slow loading speed is caused by a high data
version issue, and you do not have to shard the table. Use the compact table functionality to
trim the table down to its actual size:
tql> compact table ;

ThoughtSpot Administration Guide

Page 225

Search results contain too many blanks

December 09, 2017

Sear
Search
ch rresults
esults c
contain
ontain ttoo
oo man
many
y blanks
If you find that your search results contain too many blanks when your data source is a worksheet, there is
a simple adjustment you can make to fix this.
If you find that the charts and tables built on a worksheet contain a large number of null values (which
display as {blank} in the web browser), you can fix this by changing the inclusion rule for the worksheet.
An inclusion rule that specifies Ex
Exclude
clude Empty R
Ro
ows (Inner Join) will reduce the number of null values in
the result. Imagine a worksheet that includes data about a retail grocery store. There are rows in the
worksheet from these source tables:
Table Name

Description

sales

Fact table with sales made per product per store.

products

Dimension table with information about every product.

stores

Dimension table with information about every store.

When creating the worksheet, suppose you choose Include Empty R
Ro
ows (L
(Left
eft Out
Outer
er Join) for the inclusion
rule and Pr
Progr
ogres
essiv
sive
e Joins for the join rule. In this case, if you type “product name” in your search, you’ll
see a list of all the products that exist. Suppose you then add “store name” to your search. You will see a
lot of null ({blank}) values in the result. This happens because the columns “store name” and “product
name” are joined through the fact table, “sales”. So for every product that has never been sold in a
particular store, you’ll see {blank} in the “store name” column. This may be what you want to see, in which
case, you can leave the worksheet as is, and choose Ex
Exclude
clude for the {blank} values in your table or chart,
whenever you don’t want to see them.
However, in may cases, including all the {blank} values could confuse end users. So if you encounter this
problem, you can edit the worksheet, and change the inclusion rule to Ex
Exclude
clude Empty R
Ro
ows (Inner Join)
Join).
Now when searching for “store name” and “product name” on the worksheet, users will not be
overwhelmed by null values. They’ll only see the rows where a particular product has been sold in a
particular store.

ThoughtSpot Administration Guide

Page 226

About this reference

December 09, 2017

About this rref
efer
erenc
ence
e
This Reference section contains the commands and their syntax for all the command line tools in
ThoughtSpot.
Included in this guide are:
• Keyword reference lists the available keywords to use in your search. These are also listed in the
Help Center, which is available from Help on the top navigation bar in ThoughtSpot.
• tscli command reference lists the ThoughtSpot Command Line Interface commands.
• Formula reference lists the available formula operators and functions. These are also listed in the
Formula Assistant, which is available from the place in ThoughtSpot where you build formulas.
• Date and time formats reference lists the accepted date, time, and timestamp formats that you
can use when uploading data through the Web interface or using the ThoughtSpot Loader.
• Row level security rules reference lists the operators for building row level security rules.
• TQL reference lists the SQL commands that are supported in TQL.
• ThoughtSpot Loader flag reference lists the options for loading data with tsload.

ThoughtSpot Administration Guide

Page 227

Keyword reference

December 09, 2017

Keywor
ord
d rref
efer
erenc
ence
e
You can use keywords when asking a question to help define your search. This reference lists the various
keywords. You can also see this list of keywords and examples from within the help center.

Gener
General
al k
ke
eywor
ords
ds
Keywor
ord
d

Ex
Examples
amples

top
• top sales rep by count sales for average
revenue >10000
• sales rep average revenue for each region
top

bottom
• bottom revenue average revenue by
state
• customer by revenue for each sales rep
bottom

n
• top 10 sales rep revenue

n
• bottom 25 customer by revenue for each sales
rep

sort by
• revenue by state sort by average
revenue
• revenue by customer sort by region

ThoughtSpot Administration Guide

Page 228

Keyword reference

December 09, 2017

Da
Datte k
ke
eywor
ords
ds
Keywor
ord
d

Ex
Examples
amples

after
• order date after 10/31/2014

before
• order date before 03/01/2014

between … and ...
• order date between 01/30/2012
and 01/30/2014

day of week
• revenue by day of week last 6
months

week
• revenue by week last quarter

month
• revenue by month last year

daily
• shipments by region daily

weekly
• revenue weekly

monthly
• commission > 10000 monthly

quarterly
• sales quarterly for each product

yearly
• shipments by product yearly

day of week
• count shipments Monday

ThoughtSpot Administration Guide

Page 229

Keyword reference

Keywor
ord
d

December 09, 2017

Ex
Examples
amples

month
• commission January

month year
• commission by sales rep February
2014

year
• revenue by product 2014 product name contains
snowboard

yesterday
• sales yesterday for pro -ski200 by
store

week to date
• sales by order date week to date for
pro-ski200

month to date
• sales by product month to date sales >
2400

quarter to date
• sales by product quarter to date for top 10
products by sales

year to date
• sales by product year to date

last day
• customers last day by referrer

last week
• customers last week by store

last month
• customers last month by day

last quarter
• customers last quarter sale >300

ThoughtSpot Administration Guide

Page 230

Keyword reference

Keywor
ord
d

December 09, 2017

Ex
Examples
amples

last year
• top 10 customers last year by sale by store for
region west

n days
• visitors last 7 days

n weeks
• visitors last 10 weeks by day

n months
• visitors last 6 months for homepage visits > 30
by month

n quarters
• visitors last 2 quarters by month by
campaign

n years
• visitors last 5 years by revenue for sum
revenue >5000

growth of … by ...
• growth of sales by order
date

growth of … by … daily
• growth of sales by order
date daily

growth of … by … monthly
• growth of sales by date
shipped monthly sales > 24000

growth of … by … weekly
• growth of sales by
receipt date weekly for
proski2000

growth of … by … quarterly
• growth of sales by date
shipped quarterly

ThoughtSpot Administration Guide

Page 231

Keyword reference

Keywor
ord
d

December 09, 2017

Ex
Examples
amples

growth of … by … yearly
• growth of sales by date
closed yearly

daily year-over-year
• growth of revenue by
order date daily
year-over-year

weekly year-over-year
• growth of revenue by
date shipped weekly
year-over-year

monthly year-over-year
• growth of revenue by
receipt date monthly
year-over-year

quarterly year-over-year
• growth of revenue by
date shipped quarterly
year-over-year

n days ago
• sales 2 days ago

n weeks ago
• sales 4 weeks ago by store

n months ago
• sales 2 months ago by region

n quarters ago
• sales 4 quarters ago by product name contains
deluxe

n years ago
• sales 5 years ago by store for region
west

ThoughtSpot Administration Guide

Page 232

Keyword reference

December 09, 2017

Keywor
ord
d

Ex
Examples
amples

today
• sales today by store

next day
• shipments next day by order

next week
• shipments next week by store

next month
• appointments next month by day

next quarter
• opportunities next quarter amount >
30000

next year
• opportunities next year by sales rep

n days
• shipments next 7 days

n weeks
• shipments next 10 weeks by day

n months
• openings next 6 months location

n quarters
• opportunities next 2 quarters by
campaign

n years
• opportunities next 5 years by revenue

Time k
ke
eywor
ords
ds
Keywor
ord
d

Ex
Examples
amples

detailed
• ship time detailed

ThoughtSpot Administration Guide

Page 233

Keyword reference

December 09, 2017

Keywor
ord
d

Ex
Examples
amples

last minute
• count homepage views last minute

last hour
• count unique visits last hour

n minutes
• count visitors last 30 minutes

n hours
• count visitors last 12 hours

hourly
• visitors by page name hourly

n minutes ago
• sum inventory by product 10 minutes
ago

n hours ago
• sum inventory by product by store 2 hours
ago

Text k
ke
eywor
ords
ds
Keywor
ord
d

Ex
Examples
amples

begins with
• product name begins with 'pro'

contains
• product name contains "alpine" description
contains "snow shoe"

ends with
• product name ends with 'deluxe'

ThoughtSpot Administration Guide

Page 234

Keyword reference

Keywor
ord
d

December 09, 2017

Ex
Examples
amples

not begins with
• product name not begins with "tom's"

not contains
• product color not contains 'tan' product color
not contains 'red'

not ends with
• product name not ends with "trial"

similar to
• course name similar to 'hand'

not similar to
• course name not similar to 'hand'

Number k
ke
eywor
ords
ds
Function

Ex
Examples
amples

sum
• sum revenue

average
• average revenue by store

count
• count visitors by site

max
• max sales by visitor by site

min
• min revenue by store by campaign for cost >
5000

standard deviation
• standard deviation revenue by product by month
for date after 10/31/2010

unique count
• unique count visitor by product page last
week

ThoughtSpot Administration Guide

Page 235

Keyword reference

Function

December 09, 2017

Ex
Examples
amples

variance
• variance sale amount by visitor by product for
last year

Filt
Filter
er k
ke
eywor
ords
ds
Function

Ex
Examples
amples

between... and
• revenue between 0 and
1000

>
• sum sale amount by visitor by product for last
year sale amount
> 2000

<
• unique count visitor by product by store for
sale amount
< 20

>=
• count calls by employee lastname >= m

<=
• count shipments by city latitude <=
0

=
• unique count visitor by store purchased
products
= 3 for last 5 days

!=
• sum sale amount region != canada region
!= mexico

ThoughtSpot Administration Guide

Page 236

Keyword reference

December 09, 2017

Loca
ocation
tion k
ke
eywor
ords
ds
Keywor
ord
d

Ex
Examples
amples

near
• revenue store name county near san
francisco

near... within n miles|km|meters
• revenue store name county near alameda
within 50 miles

farther than n miles|km|meters
from

• average hours worked branch farther than 80 km
from scarborough

Location keywords only work for searches where the data source includes latitude/longitude data.

Period k
ke
eywor
ords
ds
Keywor
ord
d

Ex
Example
ample

quarter (date)

quarter (commit date)

month of quarter (date)

month of quarter (commit date)

week of year (date)

week of year (commit date)

week of quarter (date)

week of quarter (commit date)

week of month (date)

week of month (commit date)

day of year (date)

day of year (commit date)

day of quarter (date)

day of quarter (commit date)

ThoughtSpot Administration Guide

Page 237

Keyword reference

December 09, 2017

day (date)

day (order date)

day of week (date)

day of week (order date)

hour (datetime)

hour (timestamp)














ThoughtSpot Administration Guide

Page 238

TQL reference

December 09, 2017

TQL rref
efer
erenc
ence
e
TQL is the ThoughtSpot language for entering SQL commands. This reference lists TQL commands you
can use to do things like creating a schema or verifying a data load.

TQL c
commands
ommands
You can use TQL either through the ThoughtSpot application’s web interface or the command line
interface in the Linux shell.
 Not
Note:
e: Worksheets and pinboards in ThoughtSpot are dependent upon the data in the underlying tables.
Use caution when modifying tables directly. If you change or remove a schema on which those objects
rely, the objects could become invalid.
You can use TQL to view and modify schemas and data in tables. Remember to add a semicolon after
each command. Commands are not case sensitive but are capitalized here for readability.
When referring to objects using fully qualified object names, the syntax is:
"database"."schema"."table"
As a best practice, you should enclose object names (database, schema, table, and column) in double
quotes, and column values in single quotes.

Basic c
commands
ommands
Syntax

Description

Ex
Examples
amples

help

Displays command help.

TQL> help

Vie
iew
w schemas and da
data
ta
Syntax

Description

Ex
Examples
amples

SHOW DATABASES

Lists all available databases.

TQL> SHOW DATABASES;

USE 

Switches the context to the specified database.
This is required if queries do not use fully qualified names (database.schema.table) for specifying tables.

TQL> USE "fruit_database";

SHOW SCHEMAS

Lists all schemas within the current database.

TQL> SHOW SCHEMAS;

SHOW TABLES

Lists all tables within the current database by
schema.

TQL> SHOW TABLES;

SHOW TABLE 

Lists all the columns for a table.

TQL> SHOW TABLE
"locations";

ThoughtSpot Administration Guide

Page 239

TQL reference

December 09, 2017

Syntax

Description

Ex
Examples
amples

SCRIPT SERVER

Generates the TQL schema for all tables in all
databases on the server.

TQL> SCRIPT SERVER;

SCRIPT DATABASE


Generates the TQL schema for all tables in a
database.

TQL> SCRIPT DATABASE
"fruit_database";

SCRIPT TABLE 


Generates the TQL schema for a table.

TQL> SCRIPT TABLE
"vendor";

SELECT

FROM 
[WHERE
]
[GROUP BY ]
[ORDER BY ]

Shows specified set of table data.

TQL> SELECT
TOP 10 "quantity"
FROM "sales_fact";

If you do not specify the TOP number of rows to
select, the top 50 rows will be returned by default. The number of rows to return can be set using the TQL command line flag:
--query_results
_apply_top_row_count
You can use the following aggregation functions:
•
•
•
•
•
•
•
•

sum
count
count distinct
stddev
avg
variance
min
max

You can use the following date functions:
•
•
•
•
•
•

absyear
absmonth
absday
absquarter
date
time

TQL> SELECT COUNT(*)
FROM "vendor";
TQL> SELECT "vendor",
SUM("quantity")
FROM "sales_fact"
GROUP BY "vendor";
TQL> SELECT "vendor",
SUM("amount")
FROM "vendor",
"sales_fact"
WHERE
"sales_fact"."vendorid"
= "vendor"."vendorid"
AND "amount" > 100
GROUP BY "vendor"
ORDER BY "amount"
DESC;
TQL> SELECT "vendor",
SUM("quantity")
FROM "sales_fact"
GROUP BY "vendor"
LIMIT 10;

Schema cr
crea
eation
tion
Syntax

Description

Ex
Examples
amples

CREATE DATABASE


Creates a database.

TQL> CREATE DATABASE
"fruit_database";

CREATE SCHEMA


Creates a schema within the current database.

TQL> CREATE SCHEMA
"fruit_schema";

CREATE TABLE 


Creates a table with the specified column definitions and constraints.

TQL> CREATE TABLE "vendor"
("vendorid" int,
"name" varchar(255));

(
[])

Use PARTITION BY HASH to shard a table across

ThoughtSpot Administration Guide

Page 240

TQL reference

December 09, 2017

Syntax

Description

[PARTITION BY HASH
()
[KEY
("")]])

all nodes. If no KEY is specified, the table will be
randomly sharded.
Note that you can specify relationship constraints
(FOREIGN KEY or RELATIONSHIP) in the CREATE TABLE statement. But it is recommended to
define these using ALTER TABLE statements at
the end of your TQL script, after creating your tables. This works better in scripts, because it guarantees that tables are created before they are referenced in the constraint definitions.

Ex
Examples
amples
TQL> CREATE TABLE
"sales_fact"
("saleid" int,
"locationid" int,
"vendorid" int,
"quantity" int,
"sale_amount" double,
"fruitid" int,
CONSTRAINT
PRIMARY
KEY("saleid"))
PARTITION BY HASH(96)
KEY ("saleid");

Schema modifica
modification
tion
Syntax

Description

Ex
Examples
amples

DROP DATABASE


Drops a database and all of its schemas and tables.

TQL> DROP DATABASE
"fruit_database";

DROP SCHEMA


Drops a schema within the current database, and
drops all of the tables in the schema.

TQL> DROP SCHEMA
"fruit_schema";

DROP TABLE 


Drops a table.

TQL> DROP TABLE
"location";

ALTER TABLE 

ADD|DROP|RENAME
COLUMN 

Alters a table to add, drop, or rename a column.

TQL> ALTER TABLE "cart"
ADD COLUMN
"nickname"
varchar(255)
DEFAULT 'no
nickname';

When you add a column to an existing table, you
must provide a default value to use for existing
rows.

TQL> ALTER TABLE "cart"
DROP COLUMN
"nickname";
TQL> ALTER TABLE "cart"
RENAME COLUMN
"nickname"
TO "shortname";
TRUNCATE TABLE



Removes all data from a table, but preserves its
metadata, including all GUIDs, relationships, etc.
This can be used to force a new schema for a
table without losing the metadata.

TQL> TRUNCATE TABLE
"location";

However, this operation removes all existing data
from the table and must be used with caution.
You must reload the data following a TRUNCATE,
or all dependent objects (worksheets and pinboards) in ThoughtSpot will become invalid.

ThoughtSpot Administration Guide

Page 241

TQL reference

December 09, 2017

Syntax

Description

Ex
Examples
amples

ALTER TABLE 

DROP CONSTRAINT
PRIMARY KEY;

Drops the primary key from a table.

TQL> ALTER TABLE "sales"
DROP CONSTRAINT
PRIMARY KEY;

ALTER TABLE 

DROP [FOREIGN KEY|
RELATIONSHIP]
;

Note that if you then add a new primary key, the
same upsert behavior will be applied as with
adding any primary key. This can result in data
deletion, so make sure you understand how the
upsert will affect your data ahead of time.

Drops the named foreign key or relationship between two tables.

TQL> ALTER TABLE "sales"
ADD CONSTRAINT
PRIMARY KEY
("PO_number");
TQL> ALTER TABLE
"sales_fact"
DROP FOREIGN KEY
"FK_PO_number";
TQL> ALTER TABLE
"fruit_dim"
DROP RELATIONSHIP
"REL_dates";

ALTER TABLE 

DROP [CONSTRAINT
FOREIGN KEY
[]
| RELATIONSHIP
[WITH
];

You must use this syntax when dropping relationships between tables created before
ThoughtSpot version 3.2. This is because relationships could not be named in older versions.
Drops the foreign key or relationship between
two tables where you cannot reference it by relationship name. If the relationship was created
without a name, use:
•
•

the name of the referenced table, for a
foreign key.
the name of the related table, for a relationship.

If you drop a foreign key without specifying the
referenced table, all foreign keys from the table
you are altering will be dropped.

TQL> ALTER TABLE
"shipments"
DROP CONSTRAINT
FOREIGN KEY "orders";
TQL> ALTER TABLE
"wholesale_buys"
DROP RELATIONSHIP
WITH "retail_sales";
/*
Drops all
relationships
that have
wholesale_buys
as a source.
*/
TQL> ALTER TABLE
"wholesale_buys"
DROP RELATIONSHIP;
/*
Drops all foreign
keys
from wholesale_buys.
*/
TQL> ALTER TABLE
"wholesale_buys"
DROP CONSTRAINT
FOREIGN KEY;

ALTER TABLE 

[SET DIMENSION |
SET FACT
[PARTITION BY HASH
[()]
[KEY()]]]

Changes the partitioning on a table by doing one
of:
•
•
•

re-sharding a sharded table
changing a replicated table to a sharded table
changing a sharded table to a replicat-

TQL> ALTER TABLE
"sales_fact"
SET FACT
PARTITION BY HASH
(96)
KEY ("PO_number");
TQL> ALTER TABLE

ThoughtSpot Administration Guide

Page 242

TQL reference

Syntax

December 09, 2017

Description

ed (unsharded) table

Ex
Examples
amples
"fruit_dim"
SET DIMENSION;

By default, ThoughtSpot does not shard dimension tables.
To change the partitioning on a table, or to
change a dimension table to a sharded table, use
ALTER TABLE...SET FACT PARTITION BY HASH...;
To make a sharded table into a dimension table
(replicated on every node), use ALTER
TABLE...SET DIMENSION; command.

ALTER TABLE 

MODIFY COLUMN

;

Changes the data type of a column. This can
have implications on sharding and primary key
behavior. See About data type conversion.

TQL> ALTER TABLE fact100
MODIFY COLUMN
product_id int;

Modify Schema
Syntax

Description

Ex
Examples
amples

INSERT INTO


VALUES ...

Inserts values into a table. Only use this for testing. Do not use INSERT on a production system.

TQL> INSERT INTO "vendor"
VALUES 'helen rose',
'jacob norse',
'eileen ruff',
'manny gates';

UPDATE 

... SET ...
[WHERE ...]

Updates rows in a table that match optionally
provided predicates. Predicates have the form
column = value connected by the AND keyword.
Sets the column values to the specified values.

TQL> UPDATE "location"
SET "borough" =
'staten island',
"city" = 'new york'
WHERE "borough" =
'staten isl'
AND city = 'NY';

DELETE FROM

 [WHERE...]

Deletes rows from a table that match optionally
provided predicates. Predicates have the form
column = value connected by the AND keyword.

TQL> DELETE FROM "vendor"
WHERE
"name" = 'Joey Smith'
AND
"vendorid" = '19463';

Cons
onstr
traints
aints and rrela
elationships
tionships
Constraints and relationships in ThoughtSpot are used to define the relationships between tables (i.e. how
they can be joined). However, constraints are not enforced, as they would be in a transactional database.
You can define the following constraints when creating a table with CREATE TABLE, or add them to an
existing table using the ADD CONSTRAINT syntax:

ThoughtSpot Administration Guide

Page 243

TQL reference

December 09, 2017

Syntax

Description

Ex
Examples
amples

PRIMARY KEY

Designates a unique, non-null value as the
primary key for a table. This can be one column or a combination of columns.

CREATE TABLE "schools" (
"schoolID" varchar(15),
"schoolName" varchar(255),
"schoolCity" varchar(55),
"schoolState" varchar(55),
"schoolNick" varchar(55),
CONSTRAINT
PRIMARY KEY ("schoolID")
) ;

If values are not unique, an upsert will be
performed if a row includes a primary key
that is already present in the data.

TQL> ALTER TABLE "cart"
ADD CONSTRAINT
PRIMARY KEY ("cart_id");
TQL> ALTER TABLE "cart"
DROP CONSTRAINT
PRIMARY KEY "cart_id";
FOREIGN KEY

Defines a relationship where the value(s) in
the table are used to join to a second table.
Uses an equality operator. The foreign key
must match the primary key of the table that
is referenced in number, column type, and
order of columns.
When creating a foreign key, give it a name.
You can reference the foreign key name later,
if you want to remove it.

TQL> ALTER TABLE "batting"
ADD CONSTRAINT "FK_player"
FOREIGN KEY ("playerID")
REFERENCES "players"
("playerID");
TQL> ALTER TABLE "batting"
ADD CONSTRAINT "FK_lg_team"
FOREIGN KEY ("lgID"
,"teamID")
REFERENCES "teams"
("lgID" ,"teamID");
TQL> ALTER TABLE "shipment"
ADD CONSTRAINT
"FK_PO_vendor"
FOREIGN KEY ("po_number",
"vendor")
REFERENCES "orders"
("po_number", "vendor");
TQL> ALTER TABLE "shipment"
DROP CONSTRAINT
"FK_PO_vendor";

RELATIONSHIP

Defines a relationship where the value(s) in
the table can be used to join to a second
table, using an equality condition (required)
and one or more range conditions (optional).
These conditions act like a WHERE clause
when the two tables are joined. They are applied using AND logic, such that all conditions must be met for a row to be included.

TQL> ALTER TABLE
"wholesale_buys"
ADD RELATIONSHIP
"REL_fruit"
WITH "retail_sales"
AS "wholesale_buys"."fruit"
= "retail_sales"."fruit"
AND

You may add multiple relationships between
tables.

("wholesale_buys"."date_order"
<
"retail_sales"."date_sold"
AND
"retail_sales"."date_sold"
<

When creating a relationship, give it a name.
You can reference the relationship name later, if you want to remove it.

ThoughtSpot Administration Guide

Page 244

TQL reference

Syntax

December 09, 2017

Description

Ex
Examples
amples

"wholesale_buys"."expire_date");
TQL> ALTER TABLE
"wholesale_buys"
DROP RELATIONSHIP
"REL_fruit";

Flags
The --query_results_apply_top_row_count  flag can be used with TQL to limit the number
of result rows returned by a query. For example:
$ tql --query_results_apply_top_row_count 100

Da
Data
ta types
ThoughtSpot supports a simplified list of data types:
Syntax

Description

Character
•

VARCHAR(n)

•
•

DOUBLE
FLOAT

•

BOOL

•
•

INT
BIGINT

•
•
•
•

DATE
DATETIME
TIMESTAMP
TIME

Floating point

Specify the maximum number
of characters, as in VARCHAR(255). The size limit is
1GB for VARCHAR values.
DOUBLE is recommended.

Can be true or false.

Boolean

Integer

INT holds 32 bits.

Date or time

ThoughtSpot Administration Guide

Ex
Examples
amples

BIGINT holds 64 bits.

DATETIME, TIMESTAMP, and
TIME are stored at the granularity of seconds.
TIMESTAMP is identical to
DATETIME, but is included for
syntax compatibility.

Page 245

ThoughtSpot loader flag reference

December 09, 2017

ThoughtSpot loader flag rref
efer
erenc
ence
e
For recurring data loads and for scripting loads, use the ThoughtSpot Loader (tsload). This reference
section lists all the flags that can be used to modify the behavior of tsload.

Gener
General
al tsload flags
Flag

Description

--target_database


Specifies the pre-existing target database into which
tsload should load the data.

--target_schema 

Specifies the target schema.

Default is “falcon_default_schema”.

--target_table 


Specifies the tables that you
want to load into the database.

The tables must exist in the database specified by --target_database.

--empty_target

Specifies that any data in the
target table is to be removed
before the new data is
loaded.

If supplied, any rows that exist in the table
specified by --target_database and
--target table will be deleted before this
data load. To perform an “upsert” on the existing data, omit this flag or specify
--noempty_target.

--max_ignored_rows


Specifies the maximum number of rows that can be ignored if they fail to load.

If the number of ignored rows exceeds this
limit, the load will be aborted.

--bad_records_file
/

Specifies the file to use for
storing rows that failed to
load.

Input rows that do not conform to the defined
schema in ThoughtSpot will be ignored and
inserted into this file.

--date_format


Specifies the format string
for date values.

The default format is yearmonthday e.g. “Dec
30th, 2001” and is represented as 20011230.
Use the date format specifications supported
in the strptime library function.

--date_time_format



Specifies the format string
for datetime values.

The default is yearmonthday hour:minute:second e.g. Dec 30th, 2001 1:15:12 and is represented as 20011230 01:15:12. Use the datetime
format specifications supported in the strptime library function.

--time_format


Specifies the format string
for time values.

The default is hour:minute:second. Use the
time format specifications supported in the
strptime library function.

--v=[0|1|2|3

Specifies the verbosity of log
messages.

Provide a value for verbosity level. By default,
verbosity is set to the minimum, which is 0.
This value is similar to a volume control. At
higher levels your log receives more messages
and that log more frequently. This is used for

ThoughtSpot Administration Guide

Not
Notes
es

Page 246

ThoughtSpot loader flag reference

Flag

Description

December 09, 2017

Not
Notes
es
debugging. You should not change this value
unless instructed by ThoughtSpot Support.

--skip_second_fraction

Skips fractional seconds
when loading data.

If supplied, the upserts logic may be affected,
especially if the date time being loaded is a
primary key, and the data has millisecond
granularity. Load the data twice, once as a
string with a primary key, and again with second granularity date time. There is no support
to store fractional seconds in the
ThoughtSpot system.

File loading tsload flags
The following flags are used when loading data from an input file:
Flag

Description

--source_file
/

Specifies the location of the
file to be loaded.

--source_data_format
[csv|delimited]

Specifies the data file format.

--field_separator
""

Specifies the field delimiter
used in the input file.

-trailing_field_separator

Specifies that the field separator appears after every
field, including the last field
per row.

Example row with trailing field separator:
a,b,c,The default is false.

--null_value
""

Specifies how null values are
represented in the input file.

These values will be converted to NULL upon
loading.

--date_converted_to_epoch
[true|false]

Specifies whether the “date”
or “datetime” values in the input file are represented as
epoch values.

--boolean_representation
[true_false | 1_0 | T_F |
Y_N]

Specifies the format in which
boolean values are represented in the input file.

The default is T_F. You can also use this flag
to specify other values. For example, if your
data used Y for true and NULL for false, you
could specify:--boolean_representation
Y_NULL

--has_header_row

Indicates that the input file
contains a header row.

If supplied, the first row of the file is ignored. If
not supplied, the first row of the file is loaded
as data.

--escape_character
""

Specifies the escape character used in the input file.

If no value is specified, the default is “(double
quotes).

--enclosing_character
""

Specifies the enclosing character used in the input file.

If the enclosing character is double quotes,
you need to escape it, as in this example:

ThoughtSpot Administration Guide

Not
Notes
es

Optional. The default is csv.

Page 247

ThoughtSpot loader flag reference

Flag

Description

December 09, 2017

Not
Notes
es
--enclosing_character "\""

--use_bit_boolean_values
= [true | false]

Specifies how boolean values
are represented in the input
file.

ThoughtSpot Administration Guide

If supplied, the input CSV file uses a bit for
boolean values, i.e. the false value is represented as 0x0 and true as 0x1. If omitted or
set to false, boolean values are assumed to be
T_F, unless you specify something else using
the flag --boolean_representation
[true_false | 1_0 | T_F | Y_N].

Page 248

tscli command reference

December 09, 2017

tscli c
command
ommand rref
efer
erenc
ence
e
The tscli command line interface is an administration interface for the ThoughtSpot instance. Use tscli
to take snapshots (backups) of data, apply updates, stop and start the services, and view information
about the system. This reference defines each subcommand and what you can accomplish with it.
The command returns 0 upon success and a non-zero exit code upon failure. Because the tscli
command is typically running a command on multiple codes, an error may be called at different points. As
much as possible, the command attempts to save errors to the stderr directory as configured on a node.

Ho
How
w tto
o use the tscli c
command
ommand
The tscli command has the following syntax:
tscli [-h] [--helpfull] [--verbose] [--noautoconfig]
[--autoconfig] [--yes] [--cluster ]
[--zoo ] [--username username] [--identity_file identity_file]
{alert,backup,backup-policy,callhome,cluster,command,dr-mirror,etl,event,
feature,fileserver,firewall,hdfs,ldap,logs,map-tiles,monitoring,nas,node,
os,saml,scheduled-pinboards,smtp,snapshot,snapshot-policy,spot,ssl,storage,
support}
The tscli command has several subcommands such as alert, backup, and so forth. You issue a
subcommand using the following format:
tscli [subcommand ]
Subcommands have their own additional options and actions such as tscli backup create or tscli
backup delete for example. To view help for a subcommand:
tscli [subcommand] -h
A subcommand itself may have several options.

tscli subc
subcommands
ommands
This section lists each subcommand and its syntax.

alert subcommand
tscli alert [-h] {count,info,list,off,on,refresh,silence,status,unsilence}
Use this subcommand to do the following:
•
•
•
•

tscli
tscli
tscli
tscli

alert
alert
alert
alert

info Lists all alerts.
list Lists the generated alerts.
off Disables all alerts from the cluster.
on Enables alerts from the cluster.

ThoughtSpot Administration Guide

Page 249

tscli command reference

December 09, 2017

• tscli alert silence --name 
Silences the alert with alert_name. For example, DISK_ERROR. Silenced alerts are still recorded
in postgres, however emails are not sent out.
• tscli alert status Shows the status of cluster alerts.
• tscli alert unsilence-name alert_name
Unsilences the alert with *alert_name*. For example, DISK_ERROR.

backup subcommand
tscli backup [-h] {create,delete,ls,restore}
Use this subcommand to do the following:
• tscli backup create [-h] [--mode {full,light,dataless}] [--type
{full,incremental}] [--base BASE] [--storage_type {local,nas}] [--remote] name
out
Pulls a snapshot and saves it as a backup where:
◦ --mode {full,light,dataless}
Mode of backups. To understand these diffrent modes see Understand backup modes.
◦ --type {full,incremental} Type of backup.(Incremental incremental is not
implemented yet) (default: full)
◦ --base BASE
Based snapshot name for incremental backup. (Not Implemented yet) (default: None)
◦ --storage_type {local,nas}
Storage type of output directory. (default: local)
◦ --remote
Take backup through orion master. (default: True)
• tscli backup delete *name* Deletes the named backup.
• tscli backup ls List all backups taken by the system.
• tscli backup restore Restore cluster using backup.

backup-policy
tscli backup-policy [-h] {create,delete,disable,enable,ls,show,status,update}
Use this subcommand to do the following:
• tscli
policy.
• tscli
• tscli
• tscli
• tscli
• tscli
• tscli
• tscli

backup-policy create Prompts an editor for you to edit the parameters of the backup
backup-policy
backup-policy
backup-policy
backup-policy
backup-policy
backup-policy
backup-policy

delete name Deletes the backup policy with name.
disable name Disables the policy name.
enable name Enables the policy name.
ls List backup policies.
show name Show the policy name.
status name Enables the policy name.
update *name* Prompts an editor for you to edit the policy name.

ThoughtSpot Administration Guide

Page 250

tscli command reference

December 09, 2017

callhome
tscli callhome [-h] {disable,enable,generate-bundle}
Use this subcommand to do the following:
• tscli callhome disable Turns off the periodic call home feature.
• tscli callhome enable --customer_name customer_name`
Enables the “call home” feature, which sends usage statistics to ThoughtSpot Support every six
hours via the secure file server. Before using this command for the first time, you need to set up
the file server connection using tscli fileserver configure.
The parameter customer_name takes the form Shared/*`customer_name`*/stats.
• tscli callhome generate-bundle –d directory --since DAYS
◦ --d D Dest folder where tar file will be created. (default: None)
◦ --since DAYS
Grab callhome data from this time window in the past. Should be a human readable
duration string, e.g. 4h (4 hours), 30m (30 minutes), 1d (1 day). (default: None)
Generates a tar file of the cluster metrics and writes it to the specified directory where
DAYS is how far back you’d like to generate the tar file from in days. For example, 30. If
this parameter is not specified, the command will collect the stats from the last 7 days
by default.

cluster
tscli cluster [-h]
{abort-reinstall-os,check,create,get-config,load,reinstall-os,report,restore,resume-rei
nstall-os,resume-update,set-config,set-min-resource-spec,show-resource-spec,start,statu
s,stop,update,update-hadoop}
Use this subcommand to do the following:
• tscli cluster abort-reinstall-os Abort in-progress reinstall.
• tscli cluster check --includes {all,disk,zookeeper,hdfs,orion-cgroups,orionoreo} check the status nodes in the cluster.
You must specify a component to check.
• tscli cluster create release
Creates a new cluster from the release file specified by *release*. This command is used by
ThoughtSpot Support when installing a new cluster, for example, tscli cluster create
2.0.4.tar.gz
• tscli cluster get-config Get current cluster network and time configuration. Prints JSON
configuration to stdout. If for some reason the system cannot be connected to all interfaces, the
command returns an error but continues to function.
• tscli cluster load Load state from given backup onto existing cluster
• tscli cluster reinstall-os Reinstall OS on all nodes of the cluster.
• tscli cluster report Generate cluster report.

ThoughtSpot Administration Guide

Page 251

tscli command reference

December 09, 2017

• tscli cluster restore --release release_tarball backupdir`
Restores a cluster using the backup in the specified directory backupdir. If you’re restoring from
a dataless backup, you must supply the release tarball for the corresponding software release.
• tscli cluster resume-reinstall-os Resume in-progress reinstall.
• tscli cluster resume-update Resume in-progress updates.
• tscli cluster set-config Set cluster network and time configuration. Takes JSON
configuration from stdin.
• tscli cluster set-min-resource-spec Sets min resource configuration of the cluster
• tscli cluster show-resource-spec Prints default or min.
• tscli cluster start Start cluster.
• tscli cluster status Gives the status of the cluster, including release number, date last
updated, number of nodes, pending tables time, and services status.
• tscli cluster stop Pauses the cluster (but does not stop storage services).
• tscli cluster update Update existing cluster.
• tscli cluster update-hadoop Updates Hadoop/Zookeeper on the cluster.

command
tscli command [-h] {run}
Command to run a command on all nodes.
tscli command run [-h] [--nodes NODES] --dest_dir DEST_DIR [--copyfirst COPYFIRST] [-timeout TIMEOUT] command
• --nodes NODES Space separated IPs of nodes where you want to run the command. (default:
all)
• --dest_dir DEST_DIR Directory to save the files containing output from each nodes. (default:
None)
• --copyfirst COPYFIRST Copy the executable to required nodes first. (default: False)
• --timeout TIMEOUT Timeout waiting for the command to finish. (default: 60)

dr-mirror
tscli dr-mirror [-h] {start,status,stop}
• tscli dr-mirror start Starts a mirror cluster which will continuously recover from a primary
cluster.
• tscli dr-mirror status Checks whether the current cluster is running in mirror mode.
• tscli dr-mirror stop Stops mirroring on the local cluster.

entity
tscli entity [-h] {pack} ...
Creates a serialized, dataless object file for testing, troubleshooting, or migration. You can use this
command with answer, pinboard, or aggregated/unaggregated worksheet objects.
• tscli entity pack [-h] --id ID [--outdir FULLPATHNAME] Packs object metadata and
schema into a file. Packed filenames have the format XXX.YYY where XXX is ### ? optional
arguments:
◦ --id ID The required ID of the object to pack. IDs are found in thne URL of an
answer, pinboard, or aggregated/unaggregated worksheet. For example, the ID for a
pinboard http://thoughtspot.com:8088/#/pinboard/

ThoughtSpot Administration Guide

Page 252

tscli command reference

December 09, 2017

061457a2-27bc-43a9-9754-0cd873691bf0/ is
061457a2-27bc-43a9-9754-0cd873691bf0.
◦ --outdir FULLPATHNAME Directory where the command places the packed object.

etl
tscli etl [-h] {change-password,disable-lw,download-agent,enable-lw,show-lw}
• tscli etl change-password --admin_username admin_user --username
Informatica_user`
Changes the Informatica Cloud account password used by ThoughtSpot Data Connect.
Required parameters are:
◦ --admin_username admin_user specifies the Administrator username for
ThoughtSpot.
◦ --username Informatica_user specifies the username for the Informatica Cloud.
• tscli etl disable-lw Disables ThoughtSpot Data Connect.
• tscli etl download-agent Downloads the ThoughtSpot Data Connect agent to the cluster.
• tscli etl enable-lw [-h] --username USERNAME --thoughtspot_url THOUGHTSPOT_URL -admin_username ADMIN_USERNAME [--groupname GROUPNAME] --org_id ORG_ID [--pin_to
PIN_TO] [--proxy_host PROXY_HOST] [--proxy_port PROXY_PORT] [--proxy_username
PROXY_USERNAME ] [--max_wait MAX_WAIT]
You should contact ThoughtSpot Support for assistance in setting this up. Required parameters
are:
◦ --username USERNAME Username for Informatica Cloud (default: None)
◦ --thoughtspot_url THOUGHTSPOT_URL URL to reach thoughtspot. (default: None)
◦ --admin_username ADMIN_USERNAME Admin username for ThoughtSpot (default:
None)
◦ --groupname GROUPNAME
◦ --org_id ORG_ID specifies the Informatica id of the organization (company). For
ThoughtSpot, this is 001ZFA. org_id shouldn’t include the prefix Org. For example, if
on Informatica cloud, the orgid is Org003XYZ, then use only
◦ --pin_to PIN_TO specifies the IP address to pin to. If you specify an IP to pin to, that
node becomes sticky to the Informatica agent, and will always be used. Defaults to the
public IP address of the localhost where this command was run.
◦ --proxy_host PROXY_HOST Proxy server host for network access (default: )
◦ --proxy_port PROXY_PORT Proxy server port (default: )
◦ --proxy_username PROXY_USERNAME Proxy server username (default: )
◦ --max_wait MAX_WAIT Maximum time in seconds to wait for Data Connect agentto
start (default: None)
• tscli etl show-lw Shows the status of ThoughtSpot Data Connect. It also returns the
Informatica username and OrgId.

event
tscli event [-h] {list}
This subcommand has the following actions:
tscli event list [-h] [--include INCLUDE] [--since SINCE] [--from FROM] [--to TO] [-limit LIMIT] [--detail] [--summary_contains SUMMARY_CONTAINS] [--detail_contains
DETAIL_CONTAINS] [--attributes ATTRIBUTES]
• --include INCLUDE Options are all, config, notification. Default config. (default: config)
• --since SINCE Grab events from this time window in the past. Should be a human readable
duration string, e.g. 4h (4 hours), 30m (30 minutes), 1d (1 day). (default: None)

ThoughtSpot Administration Guide

Page 253

tscli command reference

December 09, 2017

--from FROM Begin timestamp, must be of the form: yyyymmdd-HH:MM (default: None)
--to TO End timestamp, must be of the form: yyyymmdd-HH:MM (default: None)
--limit LIMIT Max number of events to fetch. (default: 0)
--detail Print events in detail format. This is not tabular. Default is a tabular summary. (default:
False)
• --summary_contains SUMMARY_CONTAINS Summary of the event will be checked for this string.
Multiple strings to check for can be specified by separating them with | (event returned if it
matchesALL). Put single quotes around the param value to prevent undesired glob expansion
(default: None)
• --detail_contains DETAIL_CONTAINS Details of the event will be checked for this string.
Multiple strings to check for can be specified by separating them with | (event returned if it
matches ALL). Put single quotes around the param value to prevent undesired glob expansion
(default: None)
• --attributes ATTRIBUTES Specify attributes to match as key=value. Multiple attributes to
check for can be specified by separating them with | (event returned if it matches ALL). Put
single quotes around the param value to prevent undesired glob expansion (default: None)
•
•
•
•

feature
tscli feature [-h] {get-all-config}
This subcommand has the following actions:
tscli feature get-all-config Gets the configured features in a cluster. The command will return a list
of features, such as custom branding, Data Connect, and call home, and tell you whether they are enabled
or disabled.

fileserver
tscli fileserver [-h] {configure,download-release,purge-config,show-config,upload}
This subcommand has the following actions:
• tscli fileserver configure [-h] --user USER [--password PASSWORD ] Configures the
secure file server username and password for file upload/download and the call home feature.
You only need to issue this command once, to set up the connection to the secure file server.
You only need to reissue this command if the password changes. The parameter PASSWORD is
optional. If a password is not specified, you will be prompted to enter it.
• tscli fileserver download-release [-h] [--user USER] [--password PASSWORD]
release Downloads the specified release file and its checksum. Specify the release by number,
to the second decimal point (e.g. 3.1.0, 3.0.5, etc.). You may optionally specify the --user and -password to bypass the credentials that were specified when configuring the file server
connection with tscli fileserver configure. Before using this command for the first time,
you need to set up the file server connection using tscli fileserver configure.
• tscli fileserver purge-config Removes the file server configuration.
• tscli fileserver show-config Shows the file server configuration.
• tscli fileserver upload [-h] [--user USER] [--password PASSWORD] --file_name
FILE_NAME* –server_dir_path *SERVER_DIR_PATH`
Uploads the file specified to the directory specified on the secure file server. You may optionally
specify the --user and --password to bypass the credentials that were specified when
configuring the file server connection with tscli fileserver configure. Before using this
command for the first time, you need to set up the file server connection using tscli
fileserver configure.
Accepts these flags
◦ --user USER Username of fileserver (default: None)

ThoughtSpot Administration Guide

Page 254

tscli command reference

December 09, 2017

◦ --password PASSWORD Password of fileserver (default: None). This is required and the
command prompts you for it if you do not supply it.
◦ --file_name FILE_NAME Local file that needs to be uploaded (default: None)
◦ --server_dir_path SERVER_DIR_PATH Directory path on fileserver. (default: None)
The SERVER_DIR_PATH parameter specifies the directory to which you want to upload
the file. It is based on your customer name, and takes the form /Shared/
support/*customer_name*.

firewall
tscli firewall [-h] {close-ports,disable,enable,open-ports,status}
• tscli firewall close-ports
Closes given ports through firewall on all nodes. Takes a list of ports to close, comma separated.
Only closes ports which were previously opened using “open-ports”. Ignores ports which were
not previously opened with “open-ports” or were already closed.
• tscli firewall disable Disable firewall.
• tscli firewall enable Enable firewall.
• tscli firewall open-ports *ports*
Opens given ports through firewall on all nodes. Takes a list of ports to open, comma separated.
Ignores ports which are already open. Some essential ports are always kept open (e.g. ssh), they
are not affected by this command or by close-ports.
• tscli firewall status Shows whether firewall is currently enabled or disabled.

hdfs
tscli hdfs [-h] {leave-safemode}
This subcommand has the following actions:
tscli hdfs leave-safemode Command to get HDFS namenodes out of safemode.

ldap
tscli ldap [-h] {add-cert,configure,purge-configuration}
This subcommand has the following actions:
• tscli ldap add-cert name certificate
Adds an SSL certificate for LDAP. Use only if LDAP has been configured without SSL and you
wish to add it. Use *name* to supply an alias for the certificate you are installing.
• tscli ldap configure
Configures LDAP using an interactive script. You can see detailed instructions for setting up
LDAP in About LDAP integration.
• tscli ldap purge-configuration Purges (removes) any existing LDAP configuration.

ThoughtSpot Administration Guide

Page 255

tscli command reference

December 09, 2017

logs
tscli logs [-h] {collect,runcmd}
This subcommand has the following actions:
• tscli logs collect [-h] [--include INCLUDE] [--exclude EXCLUDE] [--since SINCE]
[--from FROM] [--to TO] [--out OUT] [--maxsize MAXSIZE] [--sizeonly] [--nodes
NODES]
Extracts logs from the cluster. Does not include any logs that have been deleted due to log
rotation.
These parameters have the following values:
◦ --include INCLUDE
Specifies a comma separated list of logs to include. Each entry is either a “selector” or
a glob for matching files.Selectors must be among: all, orion, system, ts. Anything
starting with / is assumed to be a glob pattern and interpreted via find(1). Other
entries are ignored. Put single quotes around the param value to prevent undesired
glob expansion (default: all)
◦ --exclude EXCLUDE
Comma separated list of logs to exclude. Applies to the list selected by –include.
Params are interpreted just like in –include (default: None)
◦ --since SINCE
Grab logs from this time window in the past. Should be a human readable duration
string, e.g. 4h (4 hours), 30m (30 minutes), 1d (1 day). (default: None)
◦ --from FROM Timestamp where collection begins, must be of the form: yyyymmddHH:MM (default: None)
◦ --to TO Timestamp where collection ends, must be of the form: yyyymmdd-HH:MM
(default: None)
◦ --out OUT Tarball path for dumping logs from each node (default: /tmp/
logs.tar.gz)
◦ --maxsize MAXSIZE Only fetch logs if size is smaller that this value. Can be specified
in megabytes/gigabytes, e.g. 100MB, 10GB. (default: None)
◦ --sizeonly Do not collect logs. Just report the size. (default: False)
◦ --nodes NODES Comma separated list of nodes from where to collect logs. Skip this to
use all nodes. (default: None)
• tscli logs runcmd [-h] --cmd CMD [--include INCLUDE] [--exclude EXCLUDE] [-since SINCE] [--from FROM] [--to TO] [--outfile OUTFILE] [--outdir OUTDIR] [-cmd_infmt CMD_INFMT] [--cmd_outfmt CMD_OUTFMT] [--nodes NODES]
Runs a Unix command on logs in the cluster matching the given constraints. Results are
reported as text dumped to standard out, the specified output file, or as tarballs dumped into
the specified directory.
◦ --cmd CMD
Unix-Command to be run on the selected logs. Use single quotes to escape spaces
etc. Language used to specify CMDSTR has following rules.
▪ A logfile and its corresponding result file can be referred by keywords
SRCFILE & DSTFILE. eg. cp SRCFILE DSTFILE

ThoughtSpot Administration Guide

Page 256

tscli command reference

December 09, 2017

▪ Without any reference to DSTFILE in CMDSTR, > DSTFILE will be appended
to CMDSTR for output redirection. eg du -sch SRCFILE gets autotranstalted to du -sch SRCFILE > DSTFILE
▪ Without any reference to SRCFILE, content of log is streamed to CMDSTR
via pipe. eg. tail -n100 | grep ERROR gets auto-transtalted to cat
SRCFILE | tail -n100 | grep ERROR > DSTFILE (default: None)
◦ --include INCLUDE
Comma separated list of logs to include,each entry is either a “selector” or a glob for
matching files.Selectors must be among: all, orion, system, ts. Anything starting
with / is assumed to be a glob pattern and interpreted via find(1). Other entries are
ignored. TIP: put single quotes around the param value to prevent undesired glob
expansion (default: all)
◦ --exclude EXCLUDE
Comma separated list of logs to exclude. Applies to the list selected by --include.
Params are interpreted just like in --include (default: None)
◦ --since SINCE
Grab logs from this time window in the past. Should be a human readable duration
string, e.g. 4h (4 hours), 30m (30 minutes), 1d (1 day). (default: None)
◦ --from FROM Timestamp where collection begins, must be of the form: yyyymmddHH:MM (default: None)
◦ --to TO Timestamp where collection ends, must be of the form: yyyymmdd-HH:MM
(default: None)
◦ --outfile OUTFILE File path for printing all the results. By default printed to stdout
(default: None)
◦ --outdir OUTDIR Directory path for dumping results with original dir structure from
each node. Used as an alternative to printing output to outfile/stdout (default: None)
◦ --cmd_infmt CMD_INFMT Specify if the inputfile should be compressed/uncompressed
before running CMD. C=compressed, U=uncompressed. Don’t use this flag if CMD works
on both (default: None)
◦ --cmd_outfmt CMD_OUTFMT Specify if OUTFILE generated by CMD will be compressed/
uncompressed. C=compressed, U=uncompressed. Don’t use this flag if output file will
be of same format as input file (default: None)
◦ --nodes NODES Comma separated list of nodes where to run command. Skip this to
use all nodes. (default: None)

map-tiles
tscli map-tiles [-h] {disable,enable}
This subcommand supports the following actions:
• tscli map-tiles enable [-h] [--online] [--offline] [--tar TAR] [--md5 MD5]
Enables ThoughtSpot’s map tiles, which are used when constructing geomap charts. If you don’t
have interest access, you must download the map tiles tar and md5 files. Then you must append
the following to the tscli command.
◦ --online Download maptiles tar from internet. (default: True)
◦ --offline Using maptiles tar from local disk. (default: False)
◦ --tar TAR Specified tar file for map-tiles. (default: )

ThoughtSpot Administration Guide

Page 257

tscli command reference

December 09, 2017

◦ --md5 MD5 Specified md5 file for map-tiles. (default: )
• tscli map-tiles disable Disable map-tiles functionality.

monitoring
tscli monitoring [-h] {set-config,show-config}
This subcommand has the following actions:
• tscli monitoring set-config [-h] [--email EMAIL] [--clear_email] [-heartbeat_interval HEARTBEAT_INTERVAL] [--heartbeat_disable] [--report_interval
REPORT_INTERVAL] [--report_disable] Sets the monitoring configuration.
◦ --email EMAIL Comma separated list (no spaces) of email addresses where the
cluster will send monitoring information.
◦ --clear_email Disable emails by clearing email configuration. (default: False)
◦ --heartbeat_interval HEARTBEAT_INTERVAL Heartbeat email generation interval in
seconds. Should be greater than 0.
◦ --heartbeat_disable Disable heartbeat email generation. (default: False)
◦ --report_interval REPORT_INTERVAL Cluster report email generation interval in
seconds. Should be greater than 0.
◦ --report_disable Disable cluster report email generation. (default: False)
• tscli monitoring show-config Shows the monitoring configuration.

nas
tscli nas [-h] {ls,mount-cifs,mount-nfs,unmount}
This subcommand has the following actions:
• tscli nas ls [-h] List mounts managed by NAS mounter service.
• tscli nas mount-cifs [-h] --server SERVER [--path_on_server PATH_ON_SERVER ] -mount_point MOUNT_POINT --username USERNAME --password PASSWORD [--uid UID] [--gid
GID] [--options OPTIONS ]
Mounts a CIFS device on all nodes.
◦ --server SERVER IP address or DNS name of CIFS service. For example, 10.20.30.40
(default: None)
◦ --path_on_server PATH_ON_SERVER Filesystem path on the CIFS server to mount
(source). For example: /a (default: /)
◦ --mount_point MOUNT_POINT
Directory on all cluster nodes where the NFS filesystem should be mounted (target).
This directory does not need to already exist. If this directory already exists, a new
directory is not created and the existing directory is used for mounting. For example:
/mnt/external (default: None)
◦ --username USERNAME Username to connect to the CIFS filesystem as (default: None)
◦ --password PASSWORD CIFS password for --username (default: None)
◦ --uid UID
UID that will own all files or directories on the mounted filesystem when the server
does not provide ownership information. See man mount.cifs for more details.
(default: 1001)

ThoughtSpot Administration Guide

Page 258

tscli command reference

December 09, 2017

◦ --gid GID
Gid that will own all files or directories on the mounted filesystem when the server
does not provide ownership information. See man mount.cifs for more details.
(default: 1001)
◦ --options OPTIONS Other command-line options to forward to mount.cifs
command (default: noexec)
• tscli nas mount-nfs [-h] --server SERVER [--protocol PROTO --path_on_server
PATH_ON_SERVER] --mount_point MOUNT_POINT [--options OPTIONS]
Mounts a NFS device on all nodes. Parameters are:
◦ --server SERVER IP address or DNS name of NFS service. For example, 10.20.30.40
(default: None)
◦ --path_on_server PATH_ON_SERVER Filesystem path on the NFS server to mount
(source). For example: /a/b/c/d (default: /)
◦ --mount_point MOUNT_POINT
Directory on all cluster nodes where the NFS filesystem should be mounted (target).
This directory does not need to already exist. If this directory already exists, a new
directory is not created and the existing directory is used for mounting. For example:
/mnt/external (default: None)
◦ --options OPTIONS Command-line options to forward to mount command (default:
noexec).
◦ --protocol PROTO One of nfs or nfs4. The default is nfs.
• tscli nas unmount [-h] --dir DIR
Unmounts all devices from the specified DIR (directory) location. This command returns an error
if nothing is currently mounted on this directory via tscli nas mount (default: None)

node
tscli node [-h] {check,ls,reinstall-os,status}
This subcommand has the following actions:
• tscli node check [-h] [--select {reinstall-preflight}] [--secondary SECONDARY]
Run checks per node. Takes the following parameters:
◦ --select {reinstall-preflight} Select the type of node check (default:
reinstall-preflight)
◦ --secondary SECONDARY Secondary drive for reinstall-preflight (default: sdd)
• tscli node ls [-h] [--type {all,healthy,not-healthy}] Filter by node state (default:
all)
• tscli node reinstall-os [-h] [--secondary SECONDARY ] [--cluster] Reinstall OS on a
node. This takes the following parameters:
◦ --secondary SECONDARY Secondary drive to be used to carry to reinstall (default: sdd)
◦ --cluster Is the node part of a cluster (default: False)

saml
tscli saml [-h] {configure,purge-configuration}

ThoughtSpot Administration Guide

Page 259

tscli command reference

December 09, 2017

This subcommand has the following actions:
• tscli saml configure [-h] Configures SAML. To see a list of prerequisites refer to Configure
SAML.
• tscli saml purge-configuration Purges any existing SAML configuration.

scheduled-pinboards
tscli scheduled-pinboards [-h] {disable,enable}
This subcommand has the following actions:
• tscli scheduled-pinboards disable [-h] Disable scheduled pinboards for this cluster.
• tscli scheduled-pinboards enable [-h] Enables scheduled pinboards, which is disabled in
prod clusters by default.

smtp
tscli smtp [-h]
{reset-canonical-mapping,set-canonical-mapping,set-mailfromname,set-mailname,set-relayh
ost,show-canonical-mapping,show-mailfromname,show-mailname,show-relayhost}
This subcommand takes supports the following actions:
• tscli smtp reset-canonical-mapping Deletes the current postmap mapping.
• tscli smtp set-canonical-mapping [-h] new_key new_value Sets a new Postmap
mapping.
• tscli smtp set-mailfromname mailfromname Sets the name, an email address, from which
email alerts are sent, for the cluster.
• tscli smtp set-mailname mailname Sets the mailname, a domain, where email alerts are sent,
for the cluster.
• tscli smtp set-relayhost [-h] [--force FORCE] relayhost Sets the Relay Host for
SMTP (email) sent from the cluster.
◦ --force FORCE Set even if relay host is not accessible. (default: False)
• tscli smtp show-canonical-mapping Shows the current postmap mapping.
• tscli smtp show-mailfromname Shows the mailname, from which email alerts are sent, for the
cluster.
• tscli smtp show-mailname Shows the mailname, where email alerts are sent, for the cluster.
• tscli smtp show-relayhost Shows the for SMTP (email) sent from the cluster. If there is no
Relay Host configured, the command returns NOT FOUND.

snapshot
tscli snapshot [-h] {backup,create,delete,ls,restore,update-ttl}
Learn more about snapshots and backups see the Understand the backup strategies documentation. This
subcommand supports the following actions:
• tscli snapshot backup [-h] [--mode {full,light,dataless}] [--type
{full,incremental}] [--base BASE ] [--storage_type {local,nas}] [--remote] name
out
Pull snapshot out as a backup. This takes the following parameters:
◦ --mode {full,light,dataless} Mode of backups. (default: full)

ThoughtSpot Administration Guide

Page 260

tscli command reference

December 09, 2017

◦ name Name of snapshot to pull out as a backup. To list all snapshots, run tscli
snapshot ls.
◦ out Directory where backup will be written, must not already exist.
◦ --type {full,incremental} Type of backup.(Incremental backup is not
implemented yet) (default: full)
◦ --base BASE Based snapshot name for incremental backup. (Not Implemented yet)
(default: None)
◦ --storage_type {local,nas} Storage type of output directory. (default: local)
◦ --remote Take backup through Orion master. (default: True)
• tscli snapshot create [-h] name reason ttl
Creates a new snapshot with the name and reason provided. This command does not accept .
(periods), but does accept - (dashes). The ttl parameters is the number of days after which
this snapshot will be automatically deleted. A value of -1 disables automatic deletion.
• tscli snapshot delete [-h] name Deletes the named snapshot.
• tscli snapshot ls [-h] List available snapshots.
• tscli snapshot restore [-h] [--allow_release_change] [--only_service_state]
name Restore cluster to an existing snapshot. This takes the following parameters:
◦ --allow_release_change Allow restoration to a snapshot at a different release.
(default: False)
◦ --only_service_state Restore only service state. (default: False)
• tscli snapshot update-ttl [-h] [--disable DISABLE ] name ttl
Updates manual snapshot garbage collection policy.
◦ name Specifies which snapshot to update.
◦ ttl Extends the manual snapshot ttl (time-to-live) value. Use a positive value to
increase ttl. Use negative value to decrease it.
◦ --disable DISABLE Disable manual snapshot garbage collection. Setting this value to
True will override any ttl value. (default: False)

snapshot-policy
tscli snapshot-policy [-h] {disable,enable,show,update}
This subcommand supports the following actions:
• tscli snapshot-policy disable [-h] Disable snapshot policy.
• tscli snapshot-policy enable -h Enable specified snapshot policy.
• tscli snapshot-policy show [-h] Show snapshot policy.
• tscli snapshot-policy update [-h] [--config CONFIG] Update periodic snapshot config.
This takes the following parameter:
◦ --config CONFIG Text format of periodic backup policy config (default: None)

spot
tscli spot [-h] {enable}
This subcommand supports the following actions:
tscli spot [-h] {enable} Enableds Spot integrtion.

ThoughtSpot Administration Guide

Page 261

tscli command reference

December 09, 2017

ssl
tscli ssl [-h]
{add-cert,clear-min-tls-version,off,on,rm-cert,set-min-tls-version,status,tls-status}
status Shows whether of SSL authentication is enabled or disabled for the ThoughtSpot application. tlsstatus Prints the status of TLS support
This subcommand supports the following actions:
• tscli ssl add-cert [-h] key certificate Adds an SSL certificate, key pair.
• tscli ssl clear-min-tls-version [-h] Clears any customizations for the minimum TLS
version to support.
• tscli ssl off
Disables SSL. Disabling SSL will stop users from seeing a security warning when accessing
ThoughtSpot from a browser if there is no SSL certificate installed.
• tscli ssl on [-h] If SSL is enabled and there is no certificate, users will see a security
warning when accessing ThoughtSpot from a browser.
• tscli ssl rm-cert Removes the existing SSL certificate, if any.
• tscli ssl set-min-tls-version [-h] {1.0,1.1,1.2} Sets the minimum supported TLS
version. Sets the minimum SSL version to be supported by the ThoughtSpot application. Please
ensure that client browsers are enabled for this version or newer.
• tscli ssl status Shows whether SSL authentication is enabled or disabled.
• tscli ssl tls-status [-h] Prints the status of TLS support.

storage
tscli storage [-h] gc df
This subcommand supports the following actions:
• tscli storage gc [-h] [--log_age LOG_AGE ] [--force] [--localhost_only]
Garbage collect unused storage. Before issuing this command, you must stop the cluster using
tscli cluster stop. After garbage collection has completed, you can restart the cluster with
tscli cluster start. The command frees space in these directories:
◦
◦
◦
◦
◦
◦
◦

/tmp
/usr/local/scaligent/logs/
/export/logs/orion
/export/logs/oreo
/export/logs/hadoop
/export/logs/zookeeper
cores

Accepts these optional flags:
◦ --log_age LOG_AGE
Delete logs older than these many hours. Use a non-zero value ideally. A zero value will
cause all temporary files to be deleted, including say those which are just temporarily
closed while they are being passed from one component to the next. (default: 4)
◦ --force Forces deletion of all logs and temporary files regardless of age. This must

ThoughtSpot Administration Guide

Page 262

tscli command reference

December 09, 2017

only be run on a stopped cluster. (default: False)
◦ --localhost_only If used, only the logs on the localhost will be removed. If not
specified, the command acts on the entire cluster.
• tscli storage df [--mode disk|hdfs]
Checks the disk usage on the relevant mounts. Returns output similar to the Linux system
command df -h .

support
tscli support [-h]
{restart-remote,rm-admin-email,rm-admin-phone,set-admin-email,set-admin-phone,set-remot
e,show-admin-email,show-admin-phone,show-remote,start-remote,stop-remote}

This subcommand supports the following actions:
• tscli support restart-remote Restarts remote support.
• tscli support rm-admin-email Removes the email address for contacting the customer
administrator. Replaces it with the default ThoughtSpot Support email address.
• tscli support rm-admin-phone Removes the phone number for contacting the customer
administrator. Replaces it with the default ThoughtSpot Support phone number.
• tscli support set-admin-email email Sets the email address for contacting the customer
administrator. If you would like to display a blank email address, issue the command tscli
support set-admin-email ' '.
• tscli support set-admin-phone phone_number Sets the phone number for contacting the
customer administrator. Specify a phone number using any value (e.g. +1 800-508-7008 Ext.
1). If you would like to display a blank phone number, issue the command tscli support setadmin-phone.
• tscli support set-remote [-h] [--addr ADDR] [--user USER] Configures the cluster for
remote support through SSH tunneling, where ADDR is the address of support, e.g.
tunnel.thoughtspot.com, and USER is the support username.
• tscli support show-admin-email Shows the email address for customer administrator, if set.
• tscli support show-admin-phone Shows the phone number for customer administrator, if set.
• tscli support show-remote Shows the status and configuration of remote support.
• tscli support start-remote Starts remote support.
• tscli support stop-remote Stops remote support.

ThoughtSpot Administration Guide

Page 263

Date and time formats reference

December 09, 2017

Da
Datte and time fforma
ormats
ts rref
efer
erenc
ence
e
This is a references for the date and time contexts and formats you can use with ThoughtSpot. You define
data formats in specific contexts and, depending on the context, your choices in data formatting differ.
You must understand date and time when you load data in these contexts:
• using data upload from the browser
• through tsload command
• through data connect or another extract, transform, load (ETL) tool
Data loading formats do not change how data is displayed in tables and charts.
The context where you can control date and time formats is data modeling. Data modeling controls how
data is displayed in search and their resulting answers.

Da
Data
ta loading fforma
ormats
ts via tsload
When loading via the tsload command you must specify date and timestamp formats using the format
specifications defined in thestrptime library function. Data is imported based on the timezone of the node
from which tsload is run.
For date data types, the default format is %Y%m%d which translates to yearmonthday For example, Dec
30th, 2001 is represented as 20011230. For time and datetime data types, the default is %Y%m%d
%H:%M:%S which translates to yearmonthday hour:minute:second, for example, Dec 30th, 2001
1:15:12 is represented as 20011230 01:15:12.

Da
Data
ta modeling fforma
ormats
ts ffor
or br
bro
owser da
data
ta upload
These date and time formats are supported in a CSV file when uploading via the browser. You cannot
specify the date format; ThoughtSpot will pick the format that fits your data best:
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•

1/30/2014
2014-01-30
2014-1-30
30-Jan-2014
2014-Jan-30
2014-01-30 10:32 AM
2014-01-30 14:52
2014-01-30 10:32:22
2014-01-30 10:32:22 AM
2014-01-30 10:32:22.0
2014-01-30 10:32:22.0 AM
2014-01-30 10:32:22.000
2014-01-30 10:32:22.000 AM
1/30/2014
30-Jan-14
01-Mar-02 (assumes 2002)
30/1/2014 10:32 AM
30/1/2014 14:52
30/1/2014 10:32:22
30/1/2014 10:32:22 AM
30/1/2014 10:32:22.0
30/1/2014 10:32:22.0 AM
30/1/2014 10:32:22.000
30/1/2014 10:32:22.000 AM
30-Jan-14 10:32 AM
30-Jan-14 14:52
30-Jan-14 10:32:22

ThoughtSpot Administration Guide

Page 264

Date and time formats reference

•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•

December 09, 2017

30-Jan-14 10:32:22 AM
30-Jan-14 10:32:22.0
30-Jan-14 10:32:22.0 AM
30-Jan-14 10:32:22.000
30-Jan-14 10:32:22.000 AM
Fri Jan 30 2014 3:26 PM
Fri Jan 30 2014 13:46
Fri Jan 30 2014 10:32:22
Fri Jan 30 2014 10:32:22 AM
Fri Jan 30 2014 10:32:22.0
Fri Jan 30 2014 10:32:22.0 AM
Fri Jan 30 2014 10:32:22.000
Fri Jan 30 2014 10:32:22.000 AM
14:52
10:32 AM
10:32:22
10:32:22 AM
10:32:22.0
10:32:22.000
10:32:22.0 AM
10:32:22.000 AM

Da
Data
ta loading fforma
ormats
ts via da
data
ta c
connect
onnect or
another ETL ttool
ool
Data that is loaded via ETL arrives through ODBC or JDBC connection. After you extract the data from
the source and before you load it into ThoughtSpot, you must transform any date or timestamp into a
valid format for ThoughtSpot. Once transformed, no explicit data masking is required. See the data
integration guide for more details of loading data via ODBC and JDBC.

Da
Data
ta modeling fforma
ormats
ts
A user with administrative rights can configure data modeling for data on one or all files. You can set
number, date, and currency display formats. These formats define how these value types display in tables
and charts. See the Admin Guide for more information about data modeling settings. The following format
strings are available for use:
Forma
ormatt mask

Description

YYYY or yyyy

four digit year such as 2017

YY or yy

last two digits of year such as 17

M

month with no leading zero 1-12

MM

Two digit month 01-12

MMM

Three letter month such as Jan

D

Day of year without a leading zero 0-365

DD

Day of year with up to one leading zero 01-365

DDD

Day of year with up to two leading zeroes 001-365

ThoughtSpot Administration Guide

Page 265

Date and time formats reference

Forma
ormatt mask

Description

d

Day of month with no leading zero 1-31

dd

Two digit day of month 01-31

HH

Two digit 24 hour representation of hour 00-23

hh

Two digit 12 hour representation of hour 01-12

H

24 hour representation of hour with no leading zero 0-23

h

12 hour representation of hour with no leading zero 1-12

mm

Minutes 00-59

m

Minutes with no leading zero 0-59

ss

Seconds 00-59

s

Seconds with no leading zero 0-59

a

AM/PM indicator

December 09, 2017

Valid delimiters include most non-alphabet characters. This includes but is not limited to:
•
•
•
•
•
•
•

\
/
|
:
_
=

(forward slash)
(backward slash)
(pipe symbol)
(colon)
(dash)
(underscore)
(equal sign)

Examples of valid format masks you can produce for display are as follows:
•
•
•
•
•

MM/dd/yyyy
MMM
DD/MM/yyyy
MM/dd/yyyy HH:mm
DD/MM/yyyy HH:mm

ThoughtSpot Administration Guide

Page 266

Row level security rules reference

December 09, 2017

Row le
lev
vel security rules rref
efer
erenc
ence
e
ThoughtSpot allows you to create row level security rules using expressions. If an expression evaluates to
“true” for a particular row and group combination, that group will be able to see that row. This reference
lists the various operators and functions you can use to create rules.
For information on how to use the row level security functions and operators, see About Rule-Based Row
Level Security. There is a special variable called ts_groups, which you can use when creating row level
security rules. It fetches a list of the groups that the currently logged in user belongs to. For each row, f
the expression in the rule evaluates to ‘true’ for any one of these groups, that row will be shown to the
user.
You can also see this list of operators and examples from within the Rule Builder by selecting Rule
As
Assis
sistant
tant.

Con
onv
version functions
These functions can be used to convert data from one data type to another. Conversion to or from date
data types is not supported.
Function

Description

Ex
Examples
amples

to_bool

Returns the input as a boolean (true or false).

to_bool (0) = false
to_bool (married)

to_date

Accepts a date represented as an integer or text
string, and a second string parameter that can include strptime date formatting elements. Replaces all the valid strptime date formatting elements with their string counterparts and returns
the result. Does not accept epoch formatted
dates as input.

to_date (date_sold,
'%Y-%m-%d')

to_double

Returns the input as a double.

to_double ('3.14') = 3.14
to_double (revenue * .01)

to_integer

Returns the input as an integer.

to_integer ('45') + 1 = 46
to_integer (price + tax cost)

to_string

Returns the input as a text string.

to_string (45 + 1) = '46'
to_string (revenue - cost)

Da
Datte functions
Function

Description

Ex
Examples
amples

add_days

Returns the result of adding
the specified number of

add_days (01/30/2015, 5) = 02/04/2015
add_days (invoiced, 30)

ThoughtSpot Administration Guide

Page 267

Row level security rules reference

Function

Description

December 09, 2017

Ex
Examples
amples

days to the given date.
date

Returns the date portion of
a given date.

date (home visit)

day

Returns the number (1-31)
of the day for the given
date.

day (01/15/2014) = 15
day (date ordered)

day_number_of_week

Returns the number (1-7) of
the day in a week for the
given date with 1 being
Monday and 7 being Sunday.

day_number_of_week (01/30/2015) = 6
day_number_of_week (shipped)

day_number_of_year

Returns the number (1-366)
of the day in a year for the
given date.

day_number_of_year (01/30/2015) = 30
day_number_of_year (invoiced)

day_of_week

Returns the day of the
week for the given date.

day_of week (01/30/2015) = Friday
day_of_week (serviced)

diff_days

Subtracts the second date
from the first date and returns the result in number
of days, rounded down if
not exact.

diff_days (01/15/2014, 01/17/2014) =
-2
diff_days (purchased, shipped)

diff_time

Subtracts the second date
from the first date and returns the result in number
of seconds.

diff_time (01/01/2014, 01/01/2014) =
-86,400
diff_time (clicked, submitted)

hour_of_day

Returns the hour of the day
for the given date.

hour_of_day (received)

is_weekend

Returns true if the given
date falls on a Saturday or
Sunday.

is_weekend (01/31/2015) = true
is_weekend (emailed)

month

Returns the month from the
given date.

month (01/15/2014) = January
month (date ordered)

month_number

Returns the number (1-12)
of the month for the given
date.

month_number (09/20/2014) = 9
month_number (purchased)

now

Returns the current timestamp.

now ()

start_of_month

Returns `MMM yyyy` for

start_of_month ( 01/31/2015 ) = Jan

ThoughtSpot Administration Guide

Page 268

Row level security rules reference

Function

December 09, 2017

Description

Ex
Examples
amples

the first day of the month.
Your installation configuration can override this setting so that it returns a different format such as `MM/
dd/yyyy`. Speak with your
ThoughtSpot administrator
if you .

FY 2015
start_of_month (shipped)

start_of_quarter

Returns the date for the
first day of the quarter for
the given date.

start_of_quarter ( 09/18/2015 ) = Q3
FY 2015
start_of_quarter (sold)

start_of_week

Returns the date for the
first day of the week for the
given date.

start_of_week ( 06/01/2015 ) = 05/30/
2015 Week
start_of_week (emailed)

start_of_year

Returns the date for the
first day of the year for the
given date.

start_of_year ( 02/15/2015 ) = FY
2015
start_of_year (joined)

time

Returns the time portion of
a given date.

time (3/1/2002 10:32) = 10:32
time (call began)

year

Returns the year from the
given date.

year (01/15/2014) = 2014
year (date ordered)

Mix
Mixed
ed functions
These functions can be used with text and numeric data types.
Function

Description

Ex
Examples
amples

!=

Returns true if the first value is not equal
to the second value.

3 != 2 = true
revenue != 1000000

<

Returns true if the first value is less than
the second value.

3 < 2 = false
revenue < 1000000

<=

Returns true if the first value is less than
or equal to the second value.

1 <= 2 = true
revenue <= 1000000

=

Returns true if the first value is equal to
the second value.

2 = 2 = true
revenue = 1000000

>

Returns true if the first value is greater
than the second value.

3 > 2 = true
revenue > 1000000

>=

Returns true if the first value is greater

3 >= 2 = true

ThoughtSpot Administration Guide

Page 269

Row level security rules reference

Function

December 09, 2017

Description

Ex
Examples
amples

than or equal to the second value.

revenue >= 1000000

greatest

Returns the larger of the values.

greatest (20, 10) = 20
greatest (q1 revenue, q2 revenue)

least

Returns the smaller of the values.

least (20, 10) = 10
least (q1 revenue, q2 revenue)

Number functions
Function

Description

Ex
Examples
amples

?

Returns the result of multiplying
both numbers.

3 * 2 = 6
price * taxrate

+

Returns the result of adding both
numbers.

1 + 2 = 3
price + shipping

-

Returns the result of subtracting
the second number from the first.

3 - 2 = 1
revenue - tax

/

Returns the result of dividing the
first number by the second.

6 / 3 = 2
markup / retail price

^

Returns the first number raised to
the power of the second.

3 ^ 2 = 9
width ^ 2

abs

Returns the absolute value.

abs (-10) = 10
abs (profit)

acos

Returns the inverse cosine in degrees.

acos (0.5) = 60
acos (cos-satellite-angle)

asin

Returns the inverse sine (specified
in degrees).

asin (0.5) = 30
asin (sin-satellite-angle)

atan

Returns the inverse tangent in degrees.

atan (1) = 45
atan (tan-satellite-angle)

atan2

Returns the inverse tangent in degrees.

atan2 (10, 10) = 45
atan2 (longitude, latitude)

cbrt

Returns the cube root of a number.

cbrt (27) = 3
cbrt (volume)

ceil

Returns the smallest following integer.

ceil (5.9) = 6
ceil (growth rate)

ThoughtSpot Administration Guide

Page 270

Row level security rules reference

December 09, 2017

Function

Description

Ex
Examples
amples

cos

Returns the cosine of an angle
(specified in degrees).

cos (63) = 0.45
cos (beam angle)

cube

Returns the cube of a number.

cube (3) = 27
cube (length)

exp

Returns Euler’s number (~2.718)
raised to a power.

exp (2) = 7.38905609893
exp (growth)

exp2

Returns 2 raised to a power.

exp2 (3) = 8
exp2 (growth)

floor

Returns the largest previous integer.

floor (5.1) = 5
floor (growth rate)

ln

Returns the natural logarithm.

ln (7.38905609893) = 2
ln (distance)

log10

Returns the logarithm with base
10.

log10 (100) = 2
log10 (volume)

log2

Returns the logarithm with base 2
(binary logarithm).

log2 (32) = 5
log2 (volume)

mod

Returns the remainder of first
number divided by the second
number.

mod (8, 3) = 2
mod ( revenue , quantity )

pow

Returns the first number raised to
the power of the second number.

pow (5, 2) = 25
pow (width, 2)

random

Returns a random number between 0 and 1.

random ( ) = .457718
random ( )

round

Returns the first number rounded
to the second number (the default
is 1).

round (35.65, 10) = 40
round (battingavg, 100)

safe_divide

Returns the result of dividing the
first number by the second. If the
second number is 0, returns 0 instead of NaN (not a number).

safe_divide (12, 0) = 0
safe_divide (total_cost, units)

sign

Returns +1 if the number is greater
than zero, -1 if less than zero, 0 if
zero.

sign (-250) = -1
sign (growth rate)

sin

Returns the sine of an angle (specified in degrees).

sin (35) = 0.57
sin (beam angle)

ThoughtSpot Administration Guide

Page 271

Row level security rules reference

December 09, 2017

Function

Description

Ex
Examples
amples

spherical_distance

Returns the distance in km between two points on Earth.

spherical_distance (37.465191,
-122.153617, 37.421962,
-122.142174) = 4,961.96
spherical_distance
(start_latitude,
start_longitude,
start_latitude, start_longitude)

sq

Returns the square of a numeric
value.

sq (9) = 81
sq (width)

sqrt

Returns the square root.

sqrt (9) = 3
sqrt (area)

tan

Returns the tangent of an angle
(specified in degrees).

tan (35) = 0.7
tan (beam angle)

Oper
Opera
ators
Oper
Opera
ator

Description

Ex
Examples
amples

and

Returns true when both conditions
are true, otherwise returns false.

(1 = 1) and (3 > 2) = true
lastname = 'smith' and state
='texas'

if…then…else

Conditional operator.

if (3 > 2) then 'bigger' else 'not
bigger'
if (cost > 500) then 'flag' else
'approve'

ifnull

Returns the first value if it is not null,
otherwise returns the second.

ifnull (cost, 'unknown')

isnull

Returns true if the value is null.

isnull (phone)

not

Returns true if the condition is false,
otherwise returns false.

not (3 > 2) = false
not (state = 'texas')

or

Returns true when either condition is
true, otherwise returns false.

(1 = 5) or (3 > 2) = true
state = 'california' or state
='oregon'

ThoughtSpot Administration Guide

Page 272

Row level security rules reference

December 09, 2017

Text functions
Function

Description

Ex
Examples
amples

concat

Returns the one or more values
as a concatenated text string. Be
sure to use single quotes instead
of double quotes around each of
the strings.

concat ( 'hay' , 'stack' ) =
'haystack'
concat (last_name , first_name)

contains

Returns true if the first string contains the second string, otherwise
returns false.

contains ('broomstick',
'room') = true
contains (product, 'trial
version')

edit_distance

Accepts two text strings. Returns
the edit distance (minimum number of operations required to
transform one string into the other) as an integer. Works with
strings under 1023 characters.

edit_distance ('attorney',
'atty') = 4
edit_distance (color, 'red')

edit_distance_with_cap

Accepts two text strings and an
integer to specify the upper limit
cap for the edit distance (minimum number of operations required to transform one string into the other). If the edit distance
is less than or equal to the specified cap, returns the edit distance.
If it is higher than the cap, returns
the cap plus 1. Works with strings
under 1023 characters.

edit_distance_with_cap
('pokemon go', 'minecraft
pixelmon', 3) = 4
edit_distance_with_cap (event,
'burning man', 3)

similar_to

Accepts a document text string
and a search text string. Returns
true if relevance score (0-100) of
the search string with respect to
the document is greater than or
equal to 20. Relevance is based
on edit distance, number of
words in the query, and length of
words in the query which are present in the document.

similar_to ('hello world',
'hello swirl') = true
similar_to (current team,
drafted by)

similarity

Accepts a document text string
and a search text string. Returns
the relevance score (0-100) of the
search string with respect to the

similarity ('where is the
burning man concert', 'burning
man') = 46
similarity (tweet1, tweet2)

ThoughtSpot Administration Guide

Page 273

Row level security rules reference

Function

Description

December 09, 2017

Ex
Examples
amples

document. Relevance is based on
edit distance, number of words in
the query, and length of words in
the query which are present in
the document. If the two strings
are an exact match, returns 100.
spells_like

Accepts two text strings. Returns
true if they are spelled similarly
and false if they are not. Works
with strings under 1023 characters.

spells_like ('thouhgtspot',
'thoughtspot') = true
spells_like (studio,
distributor)

strlen

Returns the length of the text.

strlen ('smith') = 5
strlen (lastname)

strpos

Returns the numeric position
(starting from 0) of the first occurrence of the second string in
the first string, or -1 if not found.

strpos
('haystack_with_needles',
'needle') = 14
strpos (complaint, 'lawyer')

substr

Returns the portion of the given
string, beginning at the location
specified (starting from 0), and of
the given length.

substr ('persnickety', 3, 7) =
snicket
substr (lastname, 0, 5)

Variables
These variables can be used in your expressions.
Function

Description

Ex
Examples
amples

ts_groups

Returns the list all the groups the current logged in user belongs to. For
any row, if the expression evaluates to true for any of the groups, the
user can see that row.

ts_groups
= east

ThoughtSpot Administration Guide

Page 274

Formula reference

December 09, 2017

Formula rref
efer
erenc
ence
e
ThoughtSpot allows you to create derived columns in worksheets using formulas. This reference lists the
various operators and functions you can use to create formulas.
You can also see this list of operators and examples from within the Formula Builder by selecting Formula
As
Assis
sistant
tant.

Aggr
ggrega
egatte functions
These functions can be used to aggregate data.
Function

Description

Ex
Examples
amples

average

Returns the average of all the values of a column.

average (revenue)

count

Returns the number of rows in the table containing the column.

count (product)

cumulative_average

Takes a measure and one or more attributes. Returns the average of the measure, accumulated
by the attribute(s) in the order specified.

cumulative_average
(revenue, order
date, state)

cumulative_max

Takes a measure and one or more attributes. Returns the maximum of the measure, accumulated
by the attribute(s) in the order specified.

cumulative_max
(revenue, state)

cumulative_min

Takes a measure and one or more attributes. Returns the minimum of the measure, accumulated
by the attribute(s) in the order specified.

cumulative_min
(revenue, campaign)

cumulative_sum

Takes a measure and one or more attributes. Returns the sum of the measure, accumulated by
the attribute(s) in the order specified.

cumulative_sum
(revenue, order
date)

group_average

Takes a measure and one or more attributes. Returns the average of the measure grouped by the
attribute(s).

group_average
(revenue, customer
region, state)

group_count

Takes a measure and one or more attributes. Returns the count of the measure grouped by the
attribute(s).

group_count
(revenue, customer
region)

group_max

Takes a measure and one or more attributes. Returns the maximum of the measure grouped by
the attribute(s).

group_max
(revenue, customer
region)

group_min

Takes a measure and one or more attributes. Returns the minimum of the measure grouped by
the attribute(s).

group_min
(revenue, customer
region)

ThoughtSpot Administration Guide

Page 275

Formula reference

December 09, 2017

Function

Description

Ex
Examples
amples

group_stddev

Takes a measure and one or more attributes. Returns the standard deviation of the measure
grouped by the attribute(s).

group_stddev
(revenue, customer
region)

group_sum

Takes a measure and one or more attributes. Returns the sum of the measure grouped by the attribute(s).

group_sum
(revenue, customer
region)

group_unique_count

Takes a measure and one or more attributes. Returns the unique count of the measure grouped
by the attribute(s).

group_unique_count
(product ,
supplier)

group_variance

Takes a measure and one or more attributes. Returns the variance of the measure grouped by
the attribute(s).

group_variance
(revenue, customer
region)

max

Returns the maximum value of a column.

max (sales)

min

Returns the minimum value of a column.

min (revenue)

moving_average

Takes a measure, two integers to define the window to aggregate over, and one or more attributes. The window is (current - Num1…Current +
Num2) with both end points being included in
the window. For example, “1,1” will have a window
size of 3. To define a window that begins before
Current, specify a negative number for Num2.
Returns the average of the measure over the given window. The attributes are the ordering
columns used to compute the moving average.

moving_average
(revenue, 2, 1,
customer region)

moving_max

Takes a measure, two integers to define the window to aggregate over, and one or more attributes. The window is (current - Num1…Current +
Num2) with both end points being included in
the window. For example, “1,1” will have a window
size of 3. To define a window that begins before
Current, specify a negative number for Num2.
Returns the maximum of the measure over the
given window. The attributes are the ordering
columns used to compute the moving maximum.

moving_max
(complaints, 1, 2,
store name)

moving_min

Takes a measure, two integers to define the window to aggregate over, and one or more attributes. The window is (current - Num1…Current +
Num2) with both end points being included in
the window. For example, “1,1” will have a window
size of 3. To define a window that begins before
Current, specify a negative number for Num2.
Returns the minimum of the measure over the
given window. The attributes are the ordering
columns used to compute the moving minimum.

moving_min
(defects, 3, 1,
product)

ThoughtSpot Administration Guide

Page 276

Formula reference

December 09, 2017

Function

Description

Ex
Examples
amples

moving_sum

Takes a measure, two integers to define the window to aggregate over, and one or more attributes. The window is (current - Num1…Current +
Num2) with both end points being included in
the window. For example, “1,1” will have a window
size of 3. To define a window that begins before
Current, specify a negative number for Num2.
Returns the sum of the measure over the given
window. The attributes are the ordering columns
used to compute the moving sum.

moving_sum
(revenue, 1, 1,
order date)

stddev

Returns the standard deviation of all values of a
column.

stddev (revenue)

sum

Returns the sum of all the values of a column.

sum (revenue)

unique count

Returns the number of unique values of a column.

unique count
(customer)

variance

Returns the variance of all the values of a column.

variance (revenue)

Con
onv
version functions
These functions can be used to convert data from one data type to another. Conversion to or from date
data types is not supported.
Function

Description

Ex
Examples
amples

to_bool

Returns the input as a boolean (true or false).

to_bool (0) = false
to_bool (married)

to_date

Accepts a date represented as an integer or text
string, and a second string parameter that can include strptime date formatting elements. Replaces all the valid strptime date formatting elements with their string counterparts and returns
the result. Does not accept epoch formatted
dates as input.

to_date (date_sold,
'%Y-%m-%d')

to_double

Returns the input as a double.

to_double ('3.14') = 3.14
to_double (revenue * .01)

to_integer

Returns the input as an integer.

to_integer ('45') + 1 = 46
to_integer (price + tax cost)

to_string

Returns the input as a text string.

to_string (45 + 1) = '46'
to_string (revenue - cost)

ThoughtSpot Administration Guide

Page 277

Formula reference

December 09, 2017

Da
Datte functions
Function

Description

Ex
Examples
amples

add_days

Returns the result of adding
the specified number of
days to the given date.

add_days (01/30/2015, 5) = 02/04/2015
add_days (invoiced, 30)

date

Returns the date portion of
a given date.

date (home visit)

day

Returns the number (1-31)
of the day for the given
date.

day (01/15/2014) = 15
day (date ordered)

day_number_of_week

Returns the number (1-7) of
the day in a week for the
given date with 1 being
Monday and 7 being Sunday.

day_number_of_week (01/30/2015) = 6
day_number_of_week (shipped)

day_number_of_year

Returns the number (1-366)
of the day in a year for the
given date.

day_number_of_year (01/30/2015) = 30
day_number_of_year (invoiced)

day_of_week

Returns the day of the
week for the given date.

day_of week (01/30/2015) = Friday
day_of_week (serviced)

diff_days

Subtracts the second date
from the first date and returns the result in number
of days, rounded down if
not exact.

diff_days (01/15/2014, 01/17/2014) =
-2
diff_days (purchased, shipped)

diff_time

Subtracts the second date
from the first date and returns the result in number
of seconds.

diff_time (01/01/2014, 01/01/2014) =
-86,400
diff_time (clicked, submitted)

hour_of_day

Returns the hour of the day
for the given date.

hour_of_day (received)

is_weekend

Returns true if the given
date falls on a Saturday or
Sunday.

is_weekend (01/31/2015) = true
is_weekend (emailed)

month

Returns the month from the
given date.

month (01/15/2014) = January
month (date ordered)

ThoughtSpot Administration Guide

Page 278

Formula reference

December 09, 2017

Function

Description

Ex
Examples
amples

month_number

Returns the number (1-12)
of the month for the given
date.

month_number (09/20/2014) = 9
month_number (purchased)

now

Returns the current timestamp.

now ()

start_of_month

Returns `MMM yyyy` for
the first day of the month.
Your installation configuration can override this setting so that it returns a different format such as `MM/
dd/yyyy`. Speak with your
ThoughtSpot administrator
if you .

start_of_month ( 01/31/2015 ) = Jan
FY 2015
start_of_month (shipped)

start_of_quarter

Returns the date for the
first day of the quarter for
the given date.

start_of_quarter ( 09/18/2015 ) = Q3
FY 2015
start_of_quarter (sold)

start_of_week

Returns the date for the
first day of the week for the
given date.

start_of_week ( 06/01/2015 ) = 05/30/
2015 Week
start_of_week (emailed)

start_of_year

Returns the date for the
first day of the year for the
given date.

start_of_year ( 02/15/2015 ) = FY
2015
start_of_year (joined)

time

Returns the time portion of
a given date.

time (3/1/2002 10:32) = 10:32
time (call began)

year

Returns the year from the
given date.

year (01/15/2014) = 2014
year (date ordered)

Mix
Mixed
ed functions
These functions can be used with text and numeric data types.
Function

Description

Ex
Examples
amples

!=

Returns true if the first value is not equal
to the second value.

3 != 2 = true
revenue != 1000000

<

Returns true if the first value is less than
the second value.

3 < 2 = false
revenue < 1000000

<=

Returns true if the first value is less than
or equal to the second value.

1 <= 2 = true
revenue <= 1000000

ThoughtSpot Administration Guide

Page 279

Formula reference

December 09, 2017

Function

Description

Ex
Examples
amples

=

Returns true if the first value is equal to
the second value.

2 = 2 = true
revenue = 1000000

>

Returns true if the first value is greater
than the second value.

3 > 2 = true
revenue > 1000000

>=

Returns true if the first value is greater
than or equal to the second value.

3 >= 2 = true
revenue >= 1000000

greatest

Returns the larger of the values.

greatest (20, 10) = 20
greatest (q1 revenue, q2 revenue)

least

Returns the smaller of the values.

least (20, 10) = 10
least (q1 revenue, q2 revenue)

Number functions
Function

Description

Ex
Examples
amples

?

Returns the result of multiplying
both numbers.

3 * 2 = 6
price * taxrate

+

Returns the result of adding both
numbers.

1 + 2 = 3
price + shipping

-

Returns the result of subtracting
the second number from the first.

3 - 2 = 1
revenue - tax

/

Returns the result of dividing the
first number by the second.

6 / 3 = 2
markup / retail price

^

Returns the first number raised to
the power of the second.

3 ^ 2 = 9
width ^ 2

abs

Returns the absolute value.

abs (-10) = 10
abs (profit)

acos

Returns the inverse cosine in degrees.

acos (0.5) = 60
acos (cos-satellite-angle)

asin

Returns the inverse sine (specified
in degrees).

asin (0.5) = 30
asin (sin-satellite-angle)

atan

Returns the inverse tangent in degrees.

atan (1) = 45
atan (tan-satellite-angle)

atan2

Returns the inverse tangent in degrees.

atan2 (10, 10) = 45
atan2 (longitude, latitude)

ThoughtSpot Administration Guide

Page 280

Formula reference

December 09, 2017

Function

Description

Ex
Examples
amples

cbrt

Returns the cube root of a number.

cbrt (27) = 3
cbrt (volume)

ceil

Returns the smallest following integer.

ceil (5.9) = 6
ceil (growth rate)

cos

Returns the cosine of an angle
(specified in degrees).

cos (63) = 0.45
cos (beam angle)

cube

Returns the cube of a number.

cube (3) = 27
cube (length)

exp

Returns Euler’s number (~2.718)
raised to a power.

exp (2) = 7.38905609893
exp (growth)

exp2

Returns 2 raised to a power.

exp2 (3) = 8
exp2 (growth)

floor

Returns the largest previous integer.

floor (5.1) = 5
floor (growth rate)

ln

Returns the natural logarithm.

ln (7.38905609893) = 2
ln (distance)

log10

Returns the logarithm with base
10.

log10 (100) = 2
log10 (volume)

log2

Returns the logarithm with base 2
(binary logarithm).

log2 (32) = 5
log2 (volume)

mod

Returns the remainder of first
number divided by the second
number.

mod (8, 3) = 2
mod ( revenue , quantity )

pow

Returns the first number raised to
the power of the second number.

pow (5, 2) = 25
pow (width, 2)

random

Returns a random number between 0 and 1.

random ( ) = .457718
random ( )

round

Returns the first number rounded
to the second number (the default
is 1).

round (35.65, 10) = 40
round (battingavg, 100)

safe_divide

Returns the result of dividing the
first number by the second. If the
second number is 0, returns 0 instead of NaN (not a number).

safe_divide (12, 0) = 0
safe_divide (total_cost, units)

sign

Returns +1 if the number is greater

sign (-250) = -1

ThoughtSpot Administration Guide

Page 281

Formula reference

December 09, 2017

Function

Description

Ex
Examples
amples

than zero, -1 if less than zero, 0 if
zero.

sign (growth rate)

sin

Returns the sine of an angle (specified in degrees).

sin (35) = 0.57
sin (beam angle)

spherical_distance

Returns the distance in km between two points on Earth.

spherical_distance (37.465191,
-122.153617, 37.421962,
-122.142174) = 4,961.96
spherical_distance
(start_latitude,
start_longitude,
start_latitude, start_longitude)

sq

Returns the square of a numeric
value.

sq (9) = 81
sq (width)

sqrt

Returns the square root.

sqrt (9) = 3
sqrt (area)

tan

Returns the tangent of an angle
(specified in degrees).

tan (35) = 0.7
tan (beam angle)

Oper
Opera
ators
Oper
Opera
ator

Description

Ex
Examples
amples

and

Returns true when both conditions
are true, otherwise returns false.

(1 = 1) and (3 > 2) = true
lastname = 'smith' and state
='texas'

if…then…else

Conditional operator.

if (3 > 2) then 'bigger' else 'not
bigger'
if (cost > 500) then 'flag' else
'approve'

ifnull

Returns the first value if it is not null,
otherwise returns the second.

ifnull (cost, 'unknown')

isnull

Returns true if the value is null.

isnull (phone)

not

Returns true if the condition is false,
otherwise returns false.

not (3 > 2) = false
not (state = 'texas')

or

Returns true when either condition is
true, otherwise returns false.

(1 = 5) or (3 > 2) = true
state = 'california' or state
='oregon'

ThoughtSpot Administration Guide

Page 282

Formula reference

December 09, 2017

Text functions
Function

Description

Ex
Examples
amples

concat

Returns the one or more values
as a concatenated text string. Be
sure to use single quotes instead
of double quotes around each of
the strings.

concat ( 'hay' , 'stack' ) =
'haystack'
concat (last_name , first_name)

contains

Returns true if the first string contains the second string, otherwise
returns false.

contains ('broomstick',
'room') = true
contains (product, 'trial
version')

edit_distance

Accepts two text strings. Returns
the edit distance (minimum number of operations required to
transform one string into the other) as an integer. Works with
strings under 1023 characters.

edit_distance ('attorney',
'atty') = 4
edit_distance (color, 'red')

edit_distance_with_cap

Accepts two text strings and an
integer to specify the upper limit
cap for the edit distance (minimum number of operations required to transform one string into the other). If the edit distance
is less than or equal to the specified cap, returns the edit distance.
If it is higher than the cap, returns
the cap plus 1. Works with strings
under 1023 characters.

edit_distance_with_cap
('pokemon go', 'minecraft
pixelmon', 3) = 4
edit_distance_with_cap (event,
'burning man', 3)

similar_to

Accepts a document text string
and a search text string. Returns
true if relevance score (0-100) of
the search string with respect to
the document is greater than or
equal to 20. Relevance is based
on edit distance, number of
words in the query, and length of
words in the query which are present in the document.

similar_to ('hello world',
'hello swirl') = true
similar_to (current team,
drafted by)

similarity

Accepts a document text string
and a search text string. Returns
the relevance score (0-100) of the
search string with respect to the

similarity ('where is the
burning man concert', 'burning
man') = 46
similarity (tweet1, tweet2)

ThoughtSpot Administration Guide

Page 283

Formula reference

Function

December 09, 2017

Description

Ex
Examples
amples

document. Relevance is based on
edit distance, number of words in
the query, and length of words in
the query which are present in
the document. If the two strings
are an exact match, returns 100.
spells_like

Accepts two text strings. Returns
true if they are spelled similarly
and false if they are not. Works
with strings under 1023 characters.

spells_like ('thouhgtspot',
'thoughtspot') = true
spells_like (studio,
distributor)

strlen

Returns the length of the text.

strlen ('smith') = 5
strlen (lastname)

strpos

Returns the numeric position
(starting from 0) of the first occurrence of the second string in
the first string, or -1 if not found.

strpos
('haystack_with_needles',
'needle') = 14
strpos (complaint, 'lawyer')

substr

Returns the portion of the given
string, beginning at the location
specified (starting from 0), and of
the given length.

substr ('persnickety', 3, 7) =
snicket
substr (lastname, 0, 5)

ThoughtSpot Administration Guide

Page 284

Error code reference

December 09, 2017

Err
Error
or c
code
ode rref
efer
erenc
ence
e
Summary: List of error codes and messages.
This section lists error codes that can appear in ThoughtSpot, with summary information and actions to
take. Error codes and messages are shown in ThoughtSpot when something goes wrong. These messages
can appear in the application and in logs.
When you see an error code, you will also see a message with a brief summary of what has happened. If
there is a remediation action you can take, it will be listed in this references. If there is no action listed,
please contact ThoughtSpot Support.
 Tip: Only the base code number is listed for each error. So keep this in mind when searching through
these codes. For example, error code TS-00125 is simply listed as 125.

Metada
Metadata
ta Err
Errors
ors (100 - 4
499)|
99)|
Code

Se
Sev
verity

Summary

Details

Action

TS-100

INFO

Success. {1} has
been added to {2}.
# {1} – name of visualization # {2} –
{name/link to pinboard}

None

None

TS-101

ERROR

Failure adding {1} to
{2}

Visualization could not be
added to {2} # {1} – name
of visualization # {2} –
name/link to pinboard

None

TS-102

ERROR

Failure adding {1} to
{2} due to corruption

{1} could not be added to
{2} as the pinboard has
one or more invalid visualizations

Please try again after removing the invalid visualization(s) from {2} # {1} –
name of visualization # {2}
– name/link to pinboard

TS-103

INFO

Success. Visualization has been deleted from {1}. 1 –
name/link to pinboard

None

None

TS-104

ERROR

Failure deleting visual from {1}

Visualization could not be
deleted from the pinboard. 1 – name/link to
pinboard

None

TS-105

ERROR

Failure deleting visual from {1} due to
corruption

Visualization could not be
deleted from {1} as the
pinboard has one or more

Please try again after removing the invalid visualization(s) from the pin-

ThoughtSpot Administration Guide

Page 285

Error code reference

Code

Se
Sev
verity

December 09, 2017

Summary

Details

Action

invalid visualizations. 1 –
name/link to pinboard

board

TS-106

INFO

Success. {1} created
successfully. 1 –
name/link to pinboard

None

None

TS-107

ERROR

Failure creating {1}.
1 – name/link to pinboard

Uh oh. We’re not sure
what happened. Please
email the trace file to {adminEmail}.

None

TS-108

INFO

Sticker created successfully.

None

None

TS-109

ERROR

Failure creating the
sticker.

Uh oh. We’re not sure
what happened. Please
email the trace file to {adminEmail}.

None

TS-110

INFO

Sticker deleted successfully.

None

None

TS-111

ERROR

Failure deleting
sticker.

Uh oh. We’re not sure
what happened. Please
email the trace file to {adminEmail}.

None

TS-112

INFO

Pinboards deleted
successfully.

None

None

TS-113

ERROR

Failure deleting pinboards

Uh oh. We’re not sure
what happened. Please
email the trace file to {adminEmail}.

None

TS-114

INFO

Answers deleted
successfully.

None

None

TS-115

ERROR

Failure deleting answers

Uh oh. We’re not sure
what happened. Please
email the trace file to {adminEmail}.

None

TS-116

INFO

Tables deleted successfully.

None

None

TS-117

ERROR

Failure deleting tables

Uh oh. We’re not sure
what happened. Please
email the trace file to {ad-

None

ThoughtSpot Administration Guide

Page 286

Error code reference

Code

Se
Sev
verity

December 09, 2017

Summary

Details

Action

minEmail}.
TS-118

INFO

Relationship created successfully.

None

None

TS-119

ERROR

Failure creating relationship

Uh oh. We’re not sure
what happened. Please
email the trace file to {adminEmail}.

None

TS-120

INFO

Relationship updated successfully.

None

None

TS-121

ERROR

Failure updating the
relationship

Uh oh. We’re not sure
what happened. Please
email the trace file to {adminEmail}.

None

TS-122

INFO

Relationship deleted successfully.

None

None

TS-123

ERROR

Failure deleting the
relationship

Uh oh. We’re not sure
what happened. Please
email the trace file to {adminEmail}.

None

TS-124

ERROR

Failure fetching details for table

Uh oh. We’re not sure
what happened. Please
email the trace file to {adminEmail}.

None

TS-125

ERROR

Failure fetching details for the tables

Uh oh. We’re not sure
what happened. Please
email the trace file to {adminEmail}.

None

TS-126

ERROR

Failure fetching details for datasource

Uh oh. We’re not sure
what happened. Please
email the trace file to {adminEmail}.

None

TS-127

ERROR

Failure fetching details for datasources

Uh oh. We’re not sure
what happened. Please
email the trace file to {adminEmail}.

None

TS-128

ERROR

Failure fetching details for metadata
items

Uh oh. We’re not sure
what happened. Please
email the trace file to {adminEmail}.

None

ThoughtSpot Administration Guide

Page 287

Error code reference

December 09, 2017

Code

Se
Sev
verity

Summary

Details

Action

TS-129

ERROR

Failure opening the
answer

Uh oh. We’re not sure
what happened. Please
email the trace file to {adminEmail}.

None

TS-130

ERROR

Failure opening the
pinboard

Uh oh. We’re not sure
what happened. Please
email the trace file to {adminEmail}.

None

TS-131

ERROR

Failure opening the
worksheet

Uh oh. We’re not sure
what happened. Please
email the trace file to {adminEmail}.

None

TS-132

INFO

Table saved successfully.

None

None

TS-133

ERROR

There was a problem saving the table

Uh oh. We’re not sure
what happened. Please
email the trace file to {adminEmail}.

None

TS-134

INFO

Visualization update
successful

None

None

TS-135

ERROR

Visualization failed
to update

Uh oh. We’re not sure
what happened. Please
email the trace file to {adminEmail}.

None

TS-136

INFO

{1} saved 1 – name
of answer

None

None

TS-137

ERROR

{1} could not be
saved 1 – name of
answer

Uh oh. We’re not sure
what happened. Please
email the trace file to {adminEmail}.

None

TS-138

INFO

{1} saved 1 - name
of pinboard / link

None

None

TS-139

ERROR

{1} could not be
saved 1 - name of
pinboard / link

Uh oh. We’re not sure
what happened. Please
email the trace file to {adminEmail}.

None

TS-140

INFO

{1} saved 1 – name
of worksheet

None

None

TS-141

ERROR

{1} could not be

Uh oh. We’re not sure

None

ThoughtSpot Administration Guide

Page 288

Error code reference

Code

Se
Sev
verity

December 09, 2017

Summary

Details

saved 1 – name of
worksheet

what happened. Please
email the trace file to {adminEmail}.

Action

TS-142

INFO

{1} saved 1 – name
of answer

None

None

TS-143

ERROR

{1} could not be
saved

Uh oh. We’re not sure
what happened. Please
email the trace file to {adminEmail}. 1 – name of answer

None

TS-144

INFO

{1} saved 1 – name/
link to pinboard

None

None

TS-145

ERROR

{1} could not be
saved

Uh oh. We’re not sure
what happened. Please
email the trace file to {adminEmail}. 1 – name of
pinboard

None

TS-146

INFO

Worksheet saved

None

None

TS-147

ERROR

Worksheet could
not be saved

Uh oh. We’re not sure
what happened. Please
email the trace file to {adminEmail}.

None

TS-148

INFO

Sticker updated

None

None

TS-149

ERROR

The sticker could
not be updated

Uh oh. We’re not sure
what happened. Please
email the trace file to {adminEmail}.

None

TS-150

INFO

Successfully assigned sticker

None

None

TS-151

ERROR

The sticker could
not be assigned

Uh oh. We’re not sure
what happened. Please
email the trace file to {adminEmail}.

None

TS-152

INFO

Successfully unassigned sticker

None

None

TS-153

ERROR

The sticker could
not be unassigned

Uh oh. We’re not sure
what happened. Please
email the trace file to {adminEmail}.

None

ThoughtSpot Administration Guide

Page 289

Error code reference

December 09, 2017

Code

Se
Sev
verity

Summary

Details

Action

TS-154

ERROR

Failed to fetch
metadata list

Uh oh. We’re not sure
what happened. Please
email the trace file to {adminEmail}.

None

TS-155

ERROR

Failed to fetch table
list

Uh oh. We’re not sure
what happened. Please
email the trace file to {adminEmail}.

None

TS-156

ERROR

Failed to fetch relationship list

Uh oh. We’re not sure
what happened. Please
email the trace file to {adminEmail}.

None

TS-157

ERROR

Failed to fetch answer list

Uh oh. We’re not sure
what happened. Please
email the trace file to {adminEmail}.

None

TS-158

ERROR

Failed to fetch pinboard list

Uh oh. We’re not sure
what happened. Please
email the trace file to {adminEmail}.

None

TS-159

ERROR

Failed to fetch
worksheet list

Uh oh. We’re not sure
what happened. Please
email the trace file to {adminEmail}.

None

TS-160

ERROR

Failed to fetch aggregated worksheet
list

Uh oh. We’re not sure
what happened. Please
email the trace file to {adminEmail}.

None

TS-161

ERROR

Failed to fetch imported data list

Uh oh. We’re not sure
what happened. Please
email the trace file to {adminEmail}.

None

TS-162

ERROR

Failed to fetch system table list

Uh oh. We’re not sure
what happened. Please
email the trace file to {adminEmail}.

None

TS-163

ERROR

Failed to DB view
list

Uh oh. We’re not sure
what happened. Please
email the trace file to {adminEmail}.

None

TS-164

ERROR

Failed to fetch data
source list

Uh oh. We’re not sure
what happened. Please

None

ThoughtSpot Administration Guide

Page 290

Error code reference

Code

Se
Sev
verity

December 09, 2017

Summary

Details

Action

email the trace file to {adminEmail}.
TS-165

ERROR

Failed to fetch column list

Uh oh. We’re not sure
what happened. Please
email the trace file to {adminEmail}.

None

TS-166

ERROR

Failed to label list

Uh oh. We’re not sure
what happened. Please
email the trace file to {adminEmail}.

None

TS-167

ERROR

Failed to fetch answer

Uh oh. We’re not sure
what happened. Please
email the trace file to {adminEmail}.

None

TS-168

ERROR

Failed to fetch
worksheet

Uh oh. We’re not sure
what happened. Please
email the trace file to {adminEmail}.

None

TS-169

INFO

Aggregated worksheet {1} created 1 –
name of aggregated worksheet

None

None

TS-170

ERROR

Failure creating Aggregated Worksheet.

Uh oh. We’re not sure
what happened. Please
email the trace file to {adminEmail}.

None

TS-171

INFO

{1} updated 1 –
name of aggregated worksheet

None

None

TS-172

ERROR

{1} failed to update 1
– name of aggregated worksheet

Uh oh. We’re not sure
what happened. Please
email the trace file to {adminEmail}.

None

TS-173

ERROR

{1} failed to update 1
– name of the formula

Uh oh. We’re not sure
what happened. Please
email the trace file to {adminEmail}.

None

TS-174

ERROR

Comments cannot
be fetched

Failed to save client state

None

TS-175

ERROR

Comment cannot

Uh oh. We’re not sure

None

ThoughtSpot Administration Guide

Page 291

Error code reference

Code

Se
Sev
verity

December 09, 2017

Summary

Details

be created

what happened. Please
email the trace file to {adminEmail}.

Action

TS-176

ERROR

Comment cannot
be updated

Uh oh. We’re not sure
what happened. Please
email the trace file to {adminEmail}.

None

TS-177

ERROR

Comment cannot
be deleted

Uh oh. We’re not sure
what happened. Please
email the trace file to {adminEmail}.

None

TS-178

INFO

Rule saved successfully

None

None

TS-179

ERROR

Rule could not be
saved

We’re not sure what happened. Please email the
trace file to {adminEmail}.

None

TS-180

INFO

Rule deleted successfully

None

None

TS-181

ERROR

Rule could not be
deleted

We’re not sure what happened. Please email the
trace file to {adminEmail}.

None

TS-182

INFO

Item deleted successfully.

None

None

TS-183

ERROR

Item could not be
deleted.

We’re not sure what happened. Please email the
trace file to {adminEmail}.

None

TS-184

INFO

Related link created
successfully.

None

None

TS-185

ERROR

Related link could
not be created.

Uh oh. We’re not sure
what happened. Please
click ‘Report Problem’ to
email a report to your administrator, {adminEmail}.

None

TS-186

INFO

Related link updated successfully.

None

None

TS-187

ERROR

Related link could
not be updated.

Uh oh. We’re not sure
what happened. Please
click ‘Report Problem’ to
email a report to your ad-

None

ThoughtSpot Administration Guide

Page 292

Error code reference

Code

Se
Sev
verity

December 09, 2017

Summary

Details

Action

ministrator, {adminEmail}.
TS-188

INFO

Related link deleted
successfully.

None

None

TS-189

ERROR

Related link could
not be deleted.

Uh oh. We’re not sure
what happened. Please
click ‘Report Problem’ to
email a report to your administrator, {adminEmail}.

None

TS-190

INFO

Related link detail
fetched successfully.

None

None

TS-191

ERROR

Related link detail
could not be
fetched.

Uh oh. We’re not sure
what happened. Please
click ‘Report Problem’ to
email a report to your administrator, {adminEmail}.

None

Da
Data
ta Servic
Service
e Err
Errors
ors (500 - 6
699)
99)
Code

Se
Sev
verity

Summary

Details

Action

TS-500

ERROR

Failed to fetch
leaf level data

Failed to fetch leaf level data.

None

TS-501

ERROR

Failed to fetch excel data

Failed to fetch excel data.

None

TS-502

ERROR

Failed to fetch visualization data

Failed to fetch visuzliation data.

None

TS-503

ERROR

Failed to fetch visualizations data

Failed to fetch data for visualizations.

None

TS-504

ERROR

Failed to fetch
chart data

Failed to fetch table data.

None

TS-505

ERROR

Failed to fetch
table data

Failed to fetch table data.

None

TS-506

ERROR

Failed to fetch
worksheet data

Failed to fetch worksheet data.

None

TS-507

ERROR

Failed to fetch filter data

Failed to fetch filter data.

None

ThoughtSpot Administration Guide

Page 293

Error code reference

December 09, 2017

Code

Se
Sev
verity

Summary

Details

Action

TS-508

ERROR

Failed to fetch
headline data

Failed to fetch filter data.

None

TS-509

ERROR

Failed to fetch
natural query

Failed to fetch natural query.

None

TS-510

INFO

File upload successful

None

None

TS-511

ERROR

Failed to upload
file

Failed to upload

None

TS-512

ERROR

The pinboard data could not be
exported to pdf.

Uh oh. We’re not sure what happened. Please
click ‘Report Problem’ to email a report to your
administrator, {adminEmail}.

None

Dependenc
Dependency
y Err
Errors
ors (7
(700
00 - 7
799)
99)
Code

Se
Sev
verity

Summary

Details

Action

TS-700

ERROR

Failure fetching table dependents

Failed to fetch dependents for the
table.

None

TS-701

ERROR

Failure fetching column dependents

Failed to fetch dependents for the
column.

None

TS-702

ERROR

Failure fetching incomplete
items

Failed to fetch incomplete items.

None

Admin Servic
Service
e Err
Errors
ors (800 - 8
899)
99)
Code

Se
Sev
verity

Summary

Details

Action

TS-800

ERROR

Failure fetching MemCache stats

Failed to fetch MemCache stats.

None

TS-801

ERROR

Failure MemCache Clear

Failed to clear MemCache.

None

TS-802

ERROR

Failure searching from MemCache

Failed to search from MemCache.

None

TS-803

ERROR

Failure fetching Loggers

Failed to fetch Loggers.

None

TS-804

ERROR

Failure setting LogLevel

Failed to set Log Level.

None

TS-805

ERROR

Failure getting debug info

Failed to get debug info.

None

ThoughtSpot Administration Guide

Page 294

Error code reference

December 09, 2017

Code

Se
Sev
verity

Summary

Details

Action

TS-806

INFO

Memcache cleared successfully

None

None

TS-807

INFO

Log level set successfully

None

None

TS-808

ERROR

Failed to report problem

None

None

TS-809

INFO

Problem reported successfully

None

None

Permis
ermissions
sions Err
Errors
ors (900 - 999)
Code

Se
Sev
verity

Summary

Details

Action

TS-900

ERROR

Failure fetching table permissions

Failed to fetch table permissions.

None

TS-901

ERROR

Failure fetching answer permissions

Failed to fetch answer permissions.

None

TS-902

ERROR

Failure fetching pinboard permissions

Failed to fetch pinboard permissions.

None

TS-903

ERROR

Failure getting metadata permissions

Failed to get metadata permissions.

None

Import Da
Data
ta Err
Errors
ors (1000 - 1099)
Code

Se
Sev
verity

Summary

Details

Action

TS-1000

ERROR

Data caching failed

Data caching failed.

None

TS-1001

ERROR

Read Columns failed.

Failed to read columns.

None

TS-1002

ERROR

Failed to read keys.

Failed to read keys.

None

TS-1003

ERROR

Failed to read relationships.

Failed to read relationships.

None

TS-1004

ERROR

Failed to load data.

Failed to load data.

None

TS-1005

ERROR

Failed to create table.

Failed to create table.

None

TS-1006

ERROR

Failed to fetch data rows.

Failed to fetch data rows.

None

TS-1007

ERROR

Failed to delete files.

Failed to fetch data rows.

None

TS-1008

ERROR

Failed to abort create table.

Failed to abort create table.

None

ThoughtSpot Administration Guide

Page 295

Error code reference

December 09, 2017

Code

Se
Sev
verity

Summary

Details

Action

TS-1009

ERROR

Failed to create schema.

Failed to create schema.

None

TS-1010

ERROR

Failed to fetch table models.

Failed to fetch table models.

None

TS-1011

ERROR

Failed to fetch sample values.

Failed to fetch sample values.

None

Scheduled Jobs Err
Errors
ors (1100 - 1199)
Code

Se
Sev
verity

Summary

Details

Action

TS-1100

INFO

The list of jobs.

None

Please click ‘Report Problem’ to email a report
to your administrator.

TS-1110

INFO

Successfully created job.

None

None

TS-1111

ERROR

The job could not
be created.

None

Please click ‘Report Problem’ to email a report
to your administrator.

TS-1112

INFO

Successfully updated job.

None

None

TS-1113

ERROR

The job could not
be updated.

None

Please click ‘Report Problem’ to email a report
to your administrator.

TS-1114

INFO

Successfully deleted
jobs.

None

None

TS-1115

ERROR

The job could not
be deleted.

None

Please click ‘Report Problem’ to email a report
to your administrator.

TS-1116

INFO

The job was paused.

None

None

TS-1117

ERROR

The job could not
be paused.

None

Please click ‘Report Problem’ to email a report
to your administrator.

TS-1118

INFO

The job was resumed

None

None

TS-1119

ERROR

The job could not
be resumed.

None

Please click ‘Report Problem’ to email a report
to your administrator.

ThoughtSpot Administration Guide

Page 296

Error code reference

December 09, 2017

User A
Admin
dmin Servic
Service
e Err
Errors
ors (1200 - 13
1399)
99)
Code

Se
Sev
verity

Summary

Details

Action

TS-1200

ERROR

Failed to fetch users list

Failed to fetch users list

None

TS-1201

ERROR

Failed to fetch groups list

Failed to fetch groups list

None

TS-1202

ERROR

Failed to fetch users and groups
list

Failed to fetch users and groups
list

None

TS-1203

ERROR

Successfully created user

Successfully created user

None

TS-1204

ERROR

Failed to create user

Failed to create user

None

TS-1205

ERROR

Successfully created group

Successfully created group

None

TS-1206

ERROR

Failed to create group

Failed to create group

None

TS-1207

ERROR

Successfully updated user

Successfully updated user

None

TS-1208

ERROR

Failed to update user

Failed to update user

None

TS-1209

ERROR

Successfully updated users

Successfully updated users

None

TS-1210

ERROR

Failed to update users

Failed to update users

None

TS-1211

ERROR

Successfully updated group

Successfully updated group

None

TS-1212

ERROR

Failed to update group

Failed to update group

None

TS-1213

ERROR

Successfully updated password

Successfully updated password

None

TS-1214

ERROR

Failed to update password

Failed to update password

None

TS-1215

ERROR

Successfully deleted users

Successfully deleted users

None

TS-1216

ERROR

Failed to delete users

Failed to delete users

None

TS-1217

ERROR

Successfully deleted groups

Successfully deleted groups

None

TS-1218

ERROR

Failed to delete groups

Failed to delete groups

None

TS-1219

ERROR

Successfully assigned users to
groups

Successfully assigned users to
groups

None

TS-1220

ERROR

Failed to assign users to groups

Failed to assign users to groups

None

ThoughtSpot Administration Guide

Page 297

Error code reference

December 09, 2017

Code

Se
Sev
verity

Summary

Details

Action

TS-1221

ERROR

Failed to fetch profile pic

Failed to fetch profile pic

None

TS-1222

INFO

Successfully uploaded profile pic

None

None

TS-1223

ERROR

Failed to upload profile pic

Failed to upload profile pic

None

TS-1224

ERROR

Successfully assigned groups to
group

Failed to assign user to group

None

TS-1228

ERROR

Successfully created role

Successfully created role

None

TS-1229

ERROR

Failed to create role

Failed to create role

None

TS-1230

ERROR

Successfully deleted role

Successfully deleted role

None

TS-1231

ERROR

Failed to delete role

Failed to delete role

None

TS-1232

ERROR

Successfully updated role

Successfully updated role

None

TS-1233

ERROR

Failed to update role

Failed to update role

None

Ses
Session
sion Servic
Service
e Err
Errors
ors (1400 - 15
1599)
99)
Code

Se
Sev
verity

Summary

Details

Action

TS-1400

ERROR

Failed to fetch session info

Failed to fetch session info

None

TS-1401

ERROR

Failed to login

Uh oh. We’re not sure what happened.
Please email the trace file to {adminEmail}.

None

TS-1402

ERROR

Failed to logout

Failed to logout

None

TS-1403

ERROR

Failed to save client state

Failed to save client state

None

TS-1404

ERROR

Failed to fetch login config

Failed to fetch login config

None

TS-1405

ERROR

Failed to fetch slack config

Failed to fetch slack config

None

TS-1406

ERROR

Health check failed

Health check failed

None

TS-1407

ERROR

Failed to fetch health
portal token

Failed to fetch health portal token

None

TS-1408

ERROR

The health portal release

Uh oh. We’re not sure what happened.

None

ThoughtSpot Administration Guide

Page 298

Error code reference

Code

Se
Sev
verity

December 09, 2017

Summary

Details

name could not be retrieved

Please email the trace file to {adminEmail}.

Action

Da
Data
ta Management Servic
Service
e Err
Errors
ors (1600 - 17
1799)
99)
Code

Se
Sev
verity

Summary

Details

Action

TS-1600

ERROR

Failed to fetch data source
types

Failed to fetch data source types

None

TS-1601

ERROR

Failed to fetch data source
sample values

Failed to fetch data source sample values

None

TS-1602

ERROR

Failed to delete data
source

Failed to delete data source

None

TS-1603

ERROR

Failed to execute DDL

Failed to execute DDL

None

TS-1604

ERROR

Failed to update schedule

Failed to update schedule

None

TS-1605

ERROR

Failed to reload tasks

Failed to reload tasks

None

TS-1606

ERROR

Failed to stop tasks

Failed to stop tasks

None

TS-1607

ERROR

Failed to get creation DDL

Failed to get creation DDL

None

TS-1608

ERROR

Failed to load from data
source

Failed to load from data source

None

TS-1609

ERROR

Failed to create connection to data source

Failed to create connection to data
source

None

TS-1610

ERROR

Failed to create data
source

Failed to create data source

None

TS-1611

ERROR

Failed to connect to data
source

Failed to connect to data source

None

TS-1612

ERROR

Failed to get data source
connection field info

Failed to get data source connection
field info

None

TS-1613

ERROR

Failed to get connection
list for data source

Failed to get connection list for data
source

None

TS-1614

ERROR

Failed to get connection
attributes for data source

Failed to get connection attributes for
data source

None

TS-1615

ERROR

Failed to get connections

Failed to get connections to data

None

ThoughtSpot Administration Guide

Page 299

Error code reference

Code

Se
Sev
verity

December 09, 2017

Summary

Details

to data source

source

Action

TS-1616

ERROR

Failed to fetch data source
config

Failed to fetch data source config

None

TS-1617

ERROR

Failed to parse sql.

Failed to parse sql.

None

TS-1618

ERROR

Failed to execute sql.

Failed to execute sql.

None

TS-1619

INFO

Successfully created connection to data source

None

None

TS-1620

INFO

Successfully updated data
upload schedule

None

None

TS-1621

ERROR

Failed to execute sql.

Please check the failing command, executed {1} statements successfully.

None

TS-1622

ERROR

Lightweight data-cache
disabled

Lightweight data-cache disabled

None

TS-1623

INFO

Selected tables were
queued for loading.

Selected tables were queued for loading.

None

TS-1624

ERROR

DataType conversion error.

No mapping found for source datatype
to ThoughtSpot datatype.

None

TS-1625

INFO

Successfully reload task
started.

None

None

TS-1626

INFO

Successfully connected to
data source.

None

None

TS-1627

INFO

Successfully created data
source.

None

None

TS-1628

INFO

Successfully stopped the
tasks.

None

None

TS-1629

INFO

Successfully deleted the
connection.

None

None

TS-1630

ERROR

There was an error deleting this connection.

None

None

TS-1631

INFO

Successfully executed the
DDL.

None

None

ThoughtSpot Administration Guide

Page 300

Error code reference

December 09, 2017

Clus
Clustter S
Sta
tatus
tus Servic
Service
e Err
Errors
ors (1800 - 18
1899)
99)
Code

Se
Sev
verity

Summary

Details

Action

TS-1800

WARNING

Failed to fetch cluster information from search
service.

None

None

TS-1801

WARNING

Failed to fetch table detail information from
search service.

None

None

TS-1802

WARNING

Failed to fetch cluster information from database
service.

None

None

TS-1803

WARNING

Failed to fetch table detail information from
databse service.

None

None

TS-1804

WARNING

Failed to fetch cluster information from cluster
management service.

None

None

TS-1805

WARNING

Failed to fetch detail information from cluster
management service.

None

None

TS-1806

WARNING

Failed to fetch log from cluster management service.

None

None

TS-1807

WARNING

Failed to fetch snapshot list from cluster management service.

None

None

TS-1808

WARNING

Failed to fetch cluster information from alert
management service.

None

None

TS-1809

WARNING

Failed to fetch cluster information from event
service.

None

None

TS-1810

WARNING

Failed to fetch alerts information from alert management service.

None

None

TS-1811

WARNING

Failed to fetch events information from alert
management service.

None

None

TS-1812

INFO

Thanks for your feedback!

None

None

TS-1813

WARNING

Sorry! Unable to submit the feedback at this moment!

None

None

TS-1814

INFO

Successfully exported objects. File can be found
at {1}.

None

None

ThoughtSpot Administration Guide

Page 301

Error code reference

December 09, 2017

Code

Se
Sev
verity

Summary

Details

Action

TS-1815

ERROR

Sorry! Unable to export objects at this moment!

What happened? {1}.

None

TS-1816

INFO

Successfully imported objects

None

None

TS-1817

ERROR

Sorry! Unable to import objects at this moment!

What happened? {1}.

None

TS-1818

INFO

Successfully deleted data source object(s).

None

None

Callosum API Err
Errors
ors (9000 - 9199)
Code

Se
Sev
verity

Summary

Details

Action

TS-9000

ERROR

The data you are
trying to delete
has some dependencies

Some objects depend on the data
you are trying to delete

delete the dependencies
before deleting this data.

TS-9001

ERROR

Uh oh. We’re not
sure what happened.

Please email the trace file to {adminEmail}.

None

TS-9002

ERROR

Could not authorize user

Try logging in again

None

TS-9003

ERROR

Uh oh. We’re not
sure what happened.

Please email the trace file to {adminEmail}.

None

TS-9004

WARNING

Still loading data,
come back soon

None

None

TS-9005

ERROR

Uh oh. We’re having trouble getting data for this
request.

Please email the trace file to {adminEmail}.

None

TS-9006

ERROR

Uh oh. We’re having trouble getting data for this
request.

Please email the trace file to {adminEmail}.

None

TS-9007

ERROR

Uh oh. We’re having trouble getting data for this
request.

Please email the trace file to {adminEmail}.

None

TS-9008

ERROR

Something went

Uh oh. We’re not sure what hap-

None

ThoughtSpot Administration Guide

Page 302

Error code reference

Code

Se
Sev
verity

December 09, 2017

Summary

Details

wrong with your
search

pened. Please email the trace file
to {adminEmail}.

Action

TS-9009

ERROR

The calculation
engine has timed
out. Please try
again.

Please email the trace file to {adminEmail}.

None

TS-9010

ERROR

Cannot open Object

Object cannot be opened due to
errors in some of its dependencies

None

TS-9500

WARNING

Cannot connect
to the calculation
engine. Please try
again soon.

None

None

TS-9501

WARNING

The calculation
engine has timed
out. Please try
again.

None

None

TS-9502

WARNING

Cannot connect
to the search engine. Please try
again soon.

None

None

TS-9503

WARNING

The search engine
has timed out.
Please try again.

None

None

TS-9504

ERROR

Cannot open {1}

{1} cannot be opened due to errors
in the following dependencies 1 Type of the object Table/Answer/
Pinboard etc.

None

TS-9505

WARNING

We’re still indexing this data, try
again soon

None

None

TS-9506

ERROR

Object is not present in the system

{1} is not present in the system 1 Type of the object Table/Answer/
Pinboard etc.

None

TS-9507

ERROR

ThoughtSpot is
unreachable.

None

None

TS-Blink
Generated
Errors
(9500 9599)

ThoughtSpot Administration Guide

Page 303

Error code reference

Code

Se
Sev
verity

December 09, 2017

Summary

Details

Action

Please try again
soon

Common Err
Errors
ors (10000 - 10099)
Code

Se
Sev
verity

Summary

Details

Action

TS-10000

ERROR

A system error has occurred

Uh oh. We’re not sure what happened.
Please contact your administrator.

None

TS-10001

ERROR

Connection
failed

The metadata store is not reachable.

Please contact
your administrator

TS-10002

ERROR

The input is
invalid

Input from the client to the server is invalid.

Please contact
your administrator

TS-10003

ERROR

Unfortunately,
you can’t do
that

You are not authorized to perform {1}. #
{1} – action user is not authorized for

Please request
access from
your administrator

TS-10004

ERROR

The user
could not be
authorized

User {0} is not authorized to perform
{1}. # {0} – name of the user # {1} – action user is not authorized for

Please request
access from
your administrator

TS-10005

ERROR

The base object is missing

An underlying object referenced by this
object is missing in store.

Please contact
your administrator

TS-10006

ERROR

The connection to
Zookeeper
has failed

Zookeeper is not reachable.

Please contact
your administrator

TS-10007

ERROR

There’s invalid
parameter(s)

Invalid parameter values: {0}.

Please contact
your administrator

TS-10008

ERROR

The user cannot be found

User {0} not found in store. # {0} –
name of the user

Please contact
your administrator

TS-10009

ERROR

Cannot add
group

This group already belongs to the group
you are trying to add it to.

None

ThoughtSpot Administration Guide

Page 304

Error code reference

December 09, 2017

Falc
alcon
on Err
Errors
ors (10600 - 106
10699)
99)
Code

Se
Sev
verity

Summary

Details

Action

TS-10603

ERROR

Falcon query cancelled

None

None

Da
Data
ta Err
Errors
ors (11000 - 11099)
Code

Se
Sev
verity

Summary

Details

Action

TS-11001

ERROR

Invalid row

None

None

TS-11002

ERROR

Invalid table/query resultset

None

None

TS-11003

ERROR

Invalid column identifier

None

None

TS-11004

ERROR

Invalid visualization identifier

None

None

TS-11005

ERROR

No data

Query execution resulted in no data.

None

TS-11006

ERROR

Query execution failed

Error in query execution to Falcon.

None

TS-11007

ERROR

Answer data generation
failed

Error in Answer data generation for
Sage input.

None

TS-11008

ERROR

Data export failed

None

None

TS-11009

ERROR

Data generation failed

Error in data generation in Callosum.

None

Report Gener
Genera
ation Err
Errors
ors (12000 - 13000)
Code

Se
Sev
verity

Summary

Details

Action

TS-12700

ERROR

Error while exporting data file.

None

None

TS-12701

ERROR

Invalid input.

The definition of the job is invalid.

None

TS-12702

ERROR

No author provided.

None

None

TS-12703

ERROR

No pinboard provided.

None

None

ThoughtSpot Administration Guide

Page 305

Error code reference

December 09, 2017

Code

Se
Sev
verity

Summary

Details

Action

TS-12704

ERROR

No recipients provided.

None

None

TS-12705

ERROR

This format is not supported.

None

None

TS-12706

ERROR

No job name provided.

None

None

TS-12707

ERROR

No job description provided.

None

None

TS-12708

ERROR

Pinboard data export error.

None

None

TS-12709

ERROR

Visualization data export error.

None

None

TS-12710

ERROR

User data unavailable.

None

None

TS-12711

ERROR

Configuration information unavailable.

None

None

TS-12712

ERROR

There are too many recipients.

The max number of recipients is
1000.

None

TS-12713

ERROR

Attachment size limit exceeded.

None

None

TS-12714

ERROR

Recipient domain is not
whitelisted.

None

None

Mor
More
e Metada
Metadata
ta Err
Errors
ors (13000 - 13099)
Code

Se
Sev
verity

Summary

Details

Action

TS-13001

ERROR

Schema creation
failed

Error creating database
schema.

None

TS-13002

ERROR

Views creation
failed

Error creating view.

None

TS-13003

ERROR

The object cannot be found in
store

Object with Id: {0} of
type: {1} not found. #
{0} – identity of the object # {1} – type of object

None

TS-13004

ERROR

The object is in
an invalid state

Oject with Id: {0} of
type: {1} in invalid state.
# {0} – identity of the
object # {1} – type of
object

None

TS-13005

ERROR

Object already

Object with Id: {0} of

None

ThoughtSpot Administration Guide

Page 306

Error code reference

Code

Se
Sev
verity

December 09, 2017

Summary

Details

exists

type: {1} already exists.
# {0} – identity of the
object # {1} – type of
object

Action

TS-13006

ERROR

Invalid object
type

Invalid type: {0} provided. # {1} – type of object

None

TS-13007

ERROR

Invalid Sage
question

Insufficient or invalid input from Sage: {0}. #
{0} – the invalid input

None

TS-13008

ERROR

Invalid Sage
question

Input from from Sage –
missing columns of type:
{0}. # {0} – column type

None

TS-13009

ERROR

Invalid Sage
question

Invalid input from Sage –
invalid expression: {0}. #
{0} – the invalid expression

None

TS-13010

ERROR

Sending logical
metadata to
Sage failed

Sending logical metadata to Sage failed due to:
{0}. # {0} – reason for
failure

None

TS-13011

ERROR

Answer generation failed

Answer generation
failed due to: {0}. # {0}
– reason for failure

None

TS-13012

ERROR

Worksheet generation failed

Worksheet generation
failed due to: {0}. # {0}
– reason for failure

None

TS-13013

ERROR

Service provider
unavailable

Service provider unavailable: {0}. # {0} –
provider details

None

TS-13015

ERROR

Physical model
not loaded

None

None

TS-13016

ERROR

Invalid physical
schema proto

Inconsistency in physical
schema from Falcon:
{0}. # {0} – error details

None

TS-13017

ERROR

Invalid duplicate
columns

Duplicate columns: {0}.
# {0} – List of duplicate
column identities

None

TS-13018

ERROR

Cyclic relationship

Detected cycles: {0}. #
{0} – cycle details

None

ThoughtSpot Administration Guide

Page 307

Error code reference

December 09, 2017

Code

Se
Sev
verity

Summary

Details

Action

TS-13019

WARNING

Older physical
schema version
received

Schema update for older version: {0} received
and ignored. # {0} – received version number

None

TS-13020

ERROR

Invalid relationship

Attempted to create invalid relationship: {0}. #
{0} – relationship details

None

TS-13022

ERROR

Invalid filter values: {values}

None

None

TS-13023

ERROR

Creating relationship failed.

None

None

TS-13024

ERROR

Deleting schema
failed.

None

None

TS-13025

ERROR

Expression validation failed.

None

None

TS-13026

INFO

Load schedule
successfully disabled.

None

None

TS-13027

ERROR

Load schedule
could not be disabled.

None

None

TS-13028

ERROR

Objects fetched
from the connection are invalid
for editing datasource.

None

To proceed with editing
the datasource, please edit the connection below to
fetch valid source objects.

TS-13029

INFO

Successfully edited data source
connection.

None

None

TS-13030

ERROR

Connection test
failed.

None

Please verify connection
attributes.

Loading Err
Errors
ors (30000 - 30099)
Code

Se
Sev
verity

Summary

Details

Action

TS-30000

ERROR

Table is not ready (data loading in progress).

None

None

ThoughtSpot Administration Guide

Page 308

Error code reference

December 09, 2017

Timely Err
Errors
ors (60000 - 64
64999)
999)
Code

Se
Sev
verity

Summary

Details

Action

TS-60000

ERROR

Failed to initialize.

None

None

ThoughtSpot Administration Guide

Page 309


Source Exif Data: 
File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.4
Linearized                      : No
Producer                        : Prince 11.3 (www.princexml.com)
Keywords                        : prince-no-fallback
Title                           : | ThoughtSpot Documentation
Page Count                      : 311


EXIF Metadata provided by EXIF.tools









 






Navigation menu