Configuration

This page contains a comprehensive list of all the parameters that can be used to configure the behavior of the Scai Platform. These parameters can be specified in the scai configuration file, which can be found:

DeploymentScaiNotebookScaiWorkflow
on-premisesscainotebook-prod.conf, by default in /opt/scai/confscaiprocess-prod.conf, by default in /opt/scai/conf
AWS/opt/scai/data/scainotebook.conf-

If both files are available, the scaiprocess-prod.conf will be the one you will want to edit.

Scai configuration file

The configuration file contains entries that can be written in the HOCON language, a superset of JSON. Entries in this configuration can be specifiedwith the dot notation (e.g. scai.groupby.limit.size) or in a nested (json-like) form, e.g.

scai {  groupby {    limit {      size: 5    }  }}

or any combination of the two.

Numerical values that represent time can have units like ns, nanoseconds, us, microseconds, ms, milliseconds, s, seconds, m, minutes, h, hours, d, days.Numerical values that represent size should be specified in byte format, e.g.: 10M, 128K, 2GB, 3 MiB.

For configuring the parameters of Scai, the above description of the syntax should be sufficient. For a full reference of the syntax, please see thePlay Configuration and HOCON format

Scai and Play Framework

Scai is built on top of Play Framework and any configuration described in the Play Framework documentation also applies toScai. Below you will find the most important Play configuration parameters that impact the Scai's behavior.

scai.metadata.schema

Schema of the Scai metadata tables. This schema will be created on each data source Scai is connected to and the Scai platform requires write access to it.The metadata tables contain information like:

  • user and role definitions
  • table/column visibility and table access rights, defined on a per role basis
  • dashboard definitions
  • data source information
  • formatted definitions of views defined using Scai's editor
  • process related tables, if applicable

default: scai type: string example: scai.metadata.schema="scai"


scai.session.timeout

The default timeout of a session, before re-logging in is required.

default: 30m type: duration example: scai.session.timeout=3600s


scai.limit.size

How many tuples should, by default, be shown for Scai tables.

default: 20 type: number example: scai.limit.size=20


scai.prefetch.size

How many tuples should be prefetched for Scai tables.

default: 100 type: number example: scai.prefetch.size=100


scai.groupby.limit.size

How many tuples should, by default, be shown for Scai group by tables. Scai group by tables are the ones that aggregate the data of a main table, e.g.calculating the sales per month involves grouping on the month column and having sum of sales as a measure.

default: 5 type: number example: scai.groupby.limit.size=20


scai.replace.fks

Whether foreign key columns should be replaced with the representative columns of the referred to table. The representative column of a table isusually a unique, human-readable column that identifies the rows of the table, e.g. Customer Name, Product Name or Source Country.

default: true type: boolean example: scai.replace.fks=false


scai.maxtemptablesorviews

How many concurrent temporary views/tables a user is allowed to create. A temporary table is created each time the user loads a file through the regular Load fileinterface. This number restricts only how many temporary tables are used concurrently (i.e. it only limits how many concurrent loads it can perform, for example). Oncethe operation that created a temporary table/view is finished/aborted (e.g. after loading a file) all temporary resources are deleted.

default: 10 type: number example: scai.maxtemptablesorviews=20


http.port

The default HTTP port the Scai web server will be run on.

Only set this parameter if the Scai web server is not containerized. If the Scai web server is running inside a docker container, it is better to map the internal portusing Docker's port mapping to the desired external port.!> This parameter must be set using a Java system property, e.g. ./scainotebook -Dhttp.port.Setting it in the configuration file does not have any effect since at the time the configuration parameters are loaded, the HTTP server is already started.

default: 9000 type: number example: http.port=80


play.http.secret.key

A secret key that is used internally to encrypt/decrypt sensitive data.

Please make sure that this secret is sufficiently complex and use a generator that uses complex symbols.

If this key is changed, all the data source passwords and license keys must be reintroduced.

default: <random> type: string example: `play.http.secret.key="KD\p:Eba!q9N>\x,rkwc`w/uXW{\Xhy$_=Lw[PQN8W<PX8z=5Y>:W)#H=?\/.sGe"`


scai.auth.cookie

The name of the cookie that Scai uses internally to authorize the execution of complex queries.

default: SCAI_AUTHBY type: string example: scai.auth.cookie="SCAI_COOKIE"


scai.load.rows.buffered

How many rows should be buffered in memory when loading a file. A higher number may improve loading performance, but it may also increase the server's memory usage.

default: 1000 type: number example: scai.load.rows.buffered=5000


scai.profiling

If profiling is enabled or not. Profiling can be enabled to investigate performance of certain operations/queries. Scai profiles at least:

  • the execution time of each request sent to Scai
  • the execution time of queries sent to data source

default: false type: boolean example: scai.profiling=true


scai.db.apply.up

Whether up evolutions (changes) of the scai.metadata.schema database schema for the default (meta) data source should be applied automatically. These evolutions are not destructive and will only create additional tables/add columnsinside the scai.metadata.schema schema.

Warning! Evolutions may be applied only when the Scai platform is updated/upgraded.

default: true type: boolean example: scai.db.apply.up=false


scai.query.timeout

The timeout for SQL queries issued to the data source, in seconds. Any query/request sent to the data source that takes more than this duration will fail with a timeout exception.

default: 300 type: duration example: scai.query.timeout=500


scai.jdbc.poolSize

Maximum number of connections to the data source that Scai has open at any given time. Increase/decrease the number of connections in accordance with the number of Scai users. A goodrule of thumb is to configure this number to be equal to number_of_users + 2 /* for bookkeeping */.

default: 10 type: number example: scai.jdbc.poolSize=30


scai.limit.maxPivotDistinctValues

Maximum number of values that a column which is used in a pivot operation can have. Each of this value will be used to build a distinct column in the group by table or a separate tracein a graph.

default: 100 type: number example: scai.limit.maxPivotDistinctValues=50


scai.numeric.null.is.zero

Whether to treat a null value of a numeric column as zero to be able to properly compute totals on such columns.

default: true type: boolean example: scai.numeric.null.is.zero=false


scai.xlsx.rows.cached

When loading XLSX files, we process the files in row batches. This parameter sets the number of rows in each batch.

default: 1000 type: number example: scai.xlsx.rows.cached=2000


scai.users.can.register

Whether users are allowed to register themselves. After registration, each user must be approved/activated by an Administrator.

default: true type: boolean example: scai.users.can.register=false


scai.db.driver

The JDBC driver used for the default (meta) database connection. The meta database is currently based on H2, therefore do not modify this value.

default: org.h2.Driver type: string example: scai.db.driver="org.h2.Driver"


scai.db.url

The JDBC url used for the default database connection. Here are some example of valid urls:

  • H2: jdbc:h2:file:/opt/data/scai
  • H2: jdbc:h2:file:/home/myuser/data/scai

nodefault type: string example: scai.db.url="jdbc:h2:mem:play"


scai.db.user

The JDBC user used to authenticate on the default database connection.

nodefault type: string example: scai.db.user="sa"


scai.db.password

The JDBC password used to authenticate on the default database connection.

nodefault type: string example: scai.db.password="mypassword"


play.http.parser.maxDiskBuffer

The maximum amount of disk space Scai will use to buffer request data (e.g. loaded files).

default: 100M type: size example: play.http.parser.maxDiskBuffer=1GB


play.http.parser.maxMemoryBuffer

The maximum amount of memory space Scai will use buffer request data (e.g. loaded files).

default: 100M type: size example: play.http.parser.maxMemoryBuffer=1M


play.server.http.idleTimeout

The maximum duration idle connections to the server will be kept open. Connections will be kept open and will be idle while the client (user's browser)will be waiting for a response from the server (Scai). This can happen when Scai is performing an expensive computation (e.g. executing a time consuming query to the data source).This value should be greater than the value of scai.query.timeout.

A null value means that the Server will keep idle connections open indefinitely. Use this value with extreme care as it can cause connection starvation, i.e.an ill-intentioned user of Scai can block all connections to Scai.

default: null type: duration example: play.server.http.idleTimeout=5m


scai.console.max.num.rows

The maximum number of rows that are shown when executing non-select queries in the console, e.g. show variables for a MySQL data source.

default: 100 type: number example: scai.console.max.num.rows=500


scai.cache.max.num.cols

The maximum number of table columns that can be stored in memory for purposes of providing suggestions, e.g. console suggestions or join suggestions.

default: 1000000 type: number example: scai.cache.max.num.cols=5000000


scai.totals.timeout

For retrieving totals, this parameter defines the maximum period of time Scai waits for the query to retrieve the results. If this period passes, Scai cancels the query issued to retrieve the totals.

default: 15s type: duration example: scai.totals.timeout=5m


scai.cache.query.ttl

The minimum period the results for a query that is deemed suitable to have its results cached (see scai.cache.query.min.exectime) are stored in Scai's cache. The results for a given query can be stored longer than the period set by this parameter if it is a longer running query and scai.cache.query.ttl.multiplier is set to a non-zero value.

default: 30m type: duration example: scai.cache.query.ttl=60m


scai.cache.query.maxsize

The maximum memory Scai can use for storing query results in its cache. Note: this value is only an approximation. Set it to an appropriate value after testing multiple values and tuning it to your workload.

default: 128M type: size example: scai.cache.query.maxsize=1G


scai.cache.query.min.exectime

Only queries that take longer to run than the period defined by this parameter are cached by Scai.

default: 100ms type: duration example: scai.cache.query.min.exectime=500ms


scai.cache.query.ttl.multiplier

For longer running queries, multiply their duration with this parameter to obtain the maximum period those query results will be stored in Scai's query cache. For example, if a query takes 3 minutes to run and this parameter is set to 20, then its query results will be stored for at most 60 minutes in Scai's query cache.

default: 20 type: number example: scai.cache.query.ttl.multiplier=20


scai.js.fastoptinprod

Whether the javascript produced should be plain or minimized. By default it is minimized.

default: false type: boolean example: scai.js.fastoptinprod=true


application.langs

The languages the application uses

default: en, ro type: string example: application.langs="en, ro"


application.name

The name of the application.!> Do not change the default values in production.

default: Scai Notebook/Scai Process type: string example: application.name="My new name"application.name=Scai Process


play.filters.disabled

What play filters you would like to be disabled.!> Do not change the default values in production.

default: [] type: sequence example: play.filters.disabled += play.filters.hosts.AllowedHostsFilterapplication.name=Scai Process


pidfile.path

Sets the path of the PID file. Use "/dev/null" to disable the generation of a PID file.

nodefault type: string example: pidfile.path="/dev/null"


play.server.akka.requestTimeout

The maximum amount of time a request can take. A null means a request can take an indefinite amount of time.

default: null type: duration example: play.server.akka.requestTimeout=10m


scai.max.scale.decimal.format

When introducing decimals in Scai forms, this parameter specifies the maximum scale of such decimal columns that we apply the format to. If a decimal has a larger scale than this value, no format is applied and any decimal value can be introduced in the form and the database will trigger an error for invalid decimals.

default: 100 type: number example: scai.max.scale.decimal.format=200


scai.load.file.prefix

When loading, Scai first creates a temporary file with the uploaded chunks it receives. This file is placed in the default temporary directory and will have a name starting with this prefix.

default: __scai_load_ type: string example: scai.load.file.prefix=scai_load_file


scai.default.password.length

When creating the default user (admin) for an on-premises installation we use the last characters of the license key as the password. This parameter sets the length of such passwords.

default: 8 type: number example: scai.default.password.length=8


scai.cloud

The cloud vendor Scai is running on if any. A value of 0 means no cloud (on-premises), 1 AWS, 2 GCP, 3 Azure.

default: 0 type: number example: scai.cloud=1