---
title: Ocient Simulator
slug: yy7FTF3MT9yNKfm7ZDq8F
description: Discover how to use the Ocient simulator for testing and validating queries before deploying in production.
docTags: 
createdAt: Thu Apr 13 2023 20:06:57 GMT+0000 (Coordinated Universal Time)
updatedAt: Thu Apr 09 2026 21:41:06 GMT+0000 (Coordinated Universal Time)
---

Ocient® provides a simulated database system upon request for development or local workloads with no performance requirements.

This simulator system is a lightweight package that emulates a complete Ocient System with these features:

- SQL port for connection using any of the supported connectors from Ocient.
- No NVMe drive or Linux® huge page requirements.

:::hint{type="info"}
To request access to an Ocient simulator, please contact Ocient Support.&#x20;
:::

# Prerequisites

The Ocient simulator has these hardware and software requirements:&#x20;

**Hardware**

- 64GB system RAM
- 64-bit Intel® architecture CPU (x86)
- Allocated disk storage equal to twice the size of the data to load. &#x20;

:::hint{type="info"}
If you run the Ocient Simulator on a virtual machine, you must configure your virtual machine CPU to support AVX2 instructions by setting the CPU type to `host`.&#x20;
:::

**Software**

- Docker® [Engine](https://www.docker.com/get-started/) version 20.10.10 or greater with [Docker Compose](https://docs.docker.com/compose/) version 1.9.0 or greater.

# Install the Ocient Simulator

Ocient distributes its simulator as the tarball `simulator_archive.tar`. Upon receiving the file, you can extract it and load the container images into the Docker daemon with the provided `load_all_images.sh` file.&#x20;

:::hint{type="info"}
Some file names might differ based on the simulator release version.
:::

:::::WorkflowBlock
:::WorkflowBlockItem
From a terminal window, create a new empty directory.&#x20;

```shell
mkdir simulator_workspace
```

And then change the directory to the new one.&#x20;

```shell
cd simulator_workspace
```
:::

:::WorkflowBlockItem
Copy or move the tarball file into the new directory.&#x20;
:::

:::WorkflowBlockItem
Extract the file.&#x20;

```shell
tar xf simulator_archive.tar
```

The simulator package contains these files.&#x20;

| **File Name**                                                                             | **Description**                                                                                                                                         |
| ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `configure.sql`                                                                           | The system configuration script that bootstraps the simulator.                                                                                          |
| `docker-compose.yml`                                                                      | The [Docker Compose file](https://docs.docker.com/compose/compose-application-model/) that defines the containers that constitute the simulator system. |
| `lat_client.tar`, `lat_simulator.tar`, `ocient_jdbc_image.tar`, `rolehostd_simulator.tar` | These Docker images comprise various components of the Ocient System. <br />                                                                            |
| `jdbc.sh`                                                                                 | The JDBC CLI launch script for connection to the SQL interface of the simulator.                                                                        |
| `lat_client.sh`                                                                           | The Loading and Transformation (LAT) client launch script. The LAT client is for backward compatibility.                                                |
| `load_all_images.sh`                                                                      | This script loads all the tarball files into the Docker daemon.                                                                                         |
:::

::::WorkflowBlockItem
Load the Ocient System tarball files for the simulator.&#x20;

```shell
./load_all_images.sh
```

:::hint{type="info"}
If you do not have access privileges to the Docker daemon, you might receive the `Permission denied` error when you run `docker` commands. Use `sudo` or add your user to the Docker group.
:::

This output shows a successful load operation. The exact output of your simulator might differ depending on what version you download.

```shell
a0c3d7b00a1e: Loading layer [=====================================>]  59.26MB/59.26MB
5d75db409355: Loading layer [=====================================>]  329.6MB/329.6MB
b4f0ab1562a2: Loading layer [=====================================>]  3.072kB/3.072kB
6b6be244d498: Loading layer [=====================================>]  94.76MB/94.76MB
Loaded image: ocient/lat/simulator:2.3.0
fb4617b63504: Loading layer [=====================================>]  29.39MB/29.39MB
f5745a52e122: Loading layer [=====================================>]  4.608kB/4.608kB
d2d33759728d: Loading layer [=====================================>]  12MB/12MB
f6533a5b289e: Loading layer [=====================================>]  10.24kB/10.24kB
a3f69486f426: Loading layer [=====================================>]  23.64MB/23.64MB
84ff92691f90: Loading layer [=====================================>]  10.24kB/10.24kB
Loaded image: ocient/lat_client:2.3.0
Loaded image: ocient/jdbc:2.100
475a54c2a93d: Loading layer [=====================================>]  65.52MB/65.52MB
314fd346d653: Loading layer [=====================================>]  1.32GB/1.32GB
Loaded image: ocient/rolehostd/simulator:23.0.0-1680124029
```
::::
:::::

## Start and Configure the Cluster

Each Ocient simulator consists of a series of nodes running in their own Docker containers. The `docker compose` command enables networking, general administration, and orchestration of these nodes.

:::hint{type="info"}
The commands you use based on this section might differ with your Docker version.&#x20;

These steps use the `docker compose` command for the simulator setup. If you are using an older version of Docker with `docker-compose` (a dash instead of a space), use that instead.&#x20;
:::

:::::WorkflowBlock
::::WorkflowBlockItem
Start the cluster using the `docker compose` command.&#x20;

```shell
docker compose up -d
```

The cluster startup displays output that is similar to this output.&#x20;

```shell
[+] Running 7/7
 ⠿ Network simulator_workspace_ocientdbnet      Created                    0.1s
 ⠿ Container simulator_workspace-sql-1          Started                   20.2s
 ⠿ Container simulator_workspace-foundation0-1  Started                   15.4s
 ⠿ Container simulator_workspace-foundation2-1  Started                   17.4s
 ⠿ Container simulator_workspace-foundation1-1  Started                   16.4s
 ⠿ Container simulator_workspace-loader-1       Started                   14.4s
 ⠿ Container simulator_workspace-lat-1          Started                    7.1s
```

:::hint{type="info"}
Ensure that you run every command from the same directory where you extracted the `simulator_archive.tar.gz` archive.
:::
::::

::::WorkflowBlockItem
Using the bundled JDBC CLI, connect to the cluster and run the contents of the `configure.sql` file that is distributed with the simulator.

The JDBC CLI is bundled with the simulator as the `jdbc.sh` script. Execute this script with no arguments after starting the cluster.

```shell
./jdbc.sh
```

:::hint{type="info"}
After loading the JDBC CLI, the system prompts you to enter a username and password. The default simulator username and password are `admin@system` and `admin`.

You can also pass these credentials later in a CONNECT statement, for example:&#x20;

`CONNECT TO jdbc:ocient://sql:4050/system USER admin@system USING admin;`
:::

The interface switches to the JDBC CLI interactive mode, as indicated by the `Ocient>` prompt. Execute the configuration file. &#x20;

:::CodeblockTabs
JDBC CLI

```shell
source configure.sql;
```
:::

The configuration displays output similar to this.&#x20;

```shell
Connected to jdbc:ocient://sql:4050/system
Modified 0 rows
Modified 0 rows
Modified 0 rows
Warning: Node must be restarted for changes to take effect (the streamloader role has been added to the configuration, but the streamloader is not yet active on the node. To have this change take effect, a restart of the streamloader and foundation nodes is required)
Modified 0 rows
Modified 0 rows
Modified 0 rows
```
::::

::::WorkflowBlockItem
After completing its modifications, the simulator warns that it needs to restart for the changes to take effect. Quit the interactive mode.&#x20;

:::CodeblockTabs
JDBC CLI

```shell
quit
```
:::

Restart the cluster.&#x20;

```shell
docker compose restart
```
::::

::::WorkflowBlockItem
After the nodes restart, verify that the simulator has started and the `test` database is accessible by connecting to it with the JDBC CLI.

Launch the JDBC connector again.  &#x20;

```shell
./jdbc.sh
```

Connect to the `test` database in the JDBC CLI.&#x20;

:::CodeblockTabs
JDBC CLI

```shell
CONNECT TO jdbc:ocient://sql:4050/test;
```
:::

The system displays a confirmation message upon a successful connection.&#x20;

:::CodeblockTabs
JDBC CLI

```shell
Connected to jdbc:ocient://sql:4050/test
```
:::
::::
:::::

## Load Data

The simulator cluster includes a Loader Node, which can load data from external sources, such as an Amazon® Web Services℠ (AWS℠) S3 bucket. This section demonstrates the creation of a basic table and pipeline, which you can then use to load data from a sample data set into a simulator database.&#x20;

If you are not already in the JDBC CLI interactive mode, start it and connect to the `test` database using the steps in [Start and Configure the Cluster](./#start-and-configure-the-cluster).&#x20;

::::WorkflowBlock
:::WorkflowBlockItem
Create a table to load. Enter this `CREATE TABLE` SQL statement. This table contains columns with various data types available in the Ocient System.

```sql
CREATE TABLE loading.data_type_coverage (
    col_bigint BIGINT NULL,
    col_binary BINARY(2) NULL,
    col_boolean BOOL NULL,
    col_char CHAR(4) NULL,
    col_date DATE NULL,
    col_decimal DECIMAL(18,4) NULL,
    col_double DOUBLE NULL,
    col_float FLOAT NULL,
    col_int INT NULL,
    col_int_array INT[] NULL,
    col_ipv4 IPV4 NULL,
    col_ip IP NULL,
    col_smallint SMALLINT NULL,
    col_point POINT NULL,
    col_linestring LINESTRING NULL,
    col_polygon POLYGON NULL,
    col_time TIME NULL,
    col_timestamp TIMESTAMP NULL,
    col_tinyint TINYINT NULL,
    col_tuple tuple<<INT, VARCHAR(255)>> NULL,
    col_uuid UUID NULL,
    col_varbinary VARBINARY(255) NULL,
    col_varchar VARCHAR(255) NULL
);
```
:::

:::WorkflowBlockItem
Create a data pipeline to load the data. Enter this `CREATE PIPELINE` SQL statement.&#x20;

This pipeline loads gzip-compressed CSV files from an S3 bucket into the `data_type_coverage` table. The pipeline reads files matching the `**output*.csv.gz` pattern from the `ocient-docs` bucket, parses them as comma-delimited records with quoted fields and a header row, and maps each named header field to a target column.&#x20;

The `EXTRACT` clause includes array and tuple delimiter settings so the parser can correctly interpret complex-type values embedded in the CSV data. The `SELECT` clause applies explicit type conversions where needed — for example, ensuring that the `col_double` and `col_float` columns properly handle `NaN` values and stripping formatting characters from the timestamp field.

For details on Ocient data pipelines, see [Data Pipelines](<./SQL Reference/Data Definition Language _DDL_ Statement Reference/Data Pipelines.md>).

```sql
CREATE PIPELINE data_type_coverage_pipeline
SOURCE S3
    ENDPOINT 'https://s3.us-east-1.amazonaws.com'
    BUCKET 'ocient-docs'
    FILTER 'all_data_types/small/**output*.csv.gz'
    COMPRESSION_METHOD 'gzip'
EXTRACT
    FORMAT CSV
    NUM_HEADER_LINES 1
    FIELD_OPTIONALLY_ENCLOSED_BY '"'
    OPEN_OBJECT '('
    CLOSE_OBJECT ')'
INTO loading.data_type_coverage
SELECT
    $1 AS col_bigint,
    $2 AS col_binary,
    $3 AS col_boolean,
    $4 AS col_char,
    $5 AS col_date,
    DECIMAL($6, 18, 4) AS col_decimal,
    DOUBLE(IF(LOWER($7) = 'nan', NULL, $7)) AS col_double,
    FLOAT(IF(LOWER($8) = 'nan', NULL, $8)) AS col_float,
    $9 AS col_int,
    INT[]($10) AS col_int_array,
    $11 AS col_ipv4,
    $12 AS col_ip,
    $13 AS col_smallint,
    $14 AS col_point,
    $15 AS col_linestring,
    $16 AS col_polygon,
    $17 AS col_time,
    REPLACE(REPLACE($18, 'T', ' '), 'Z', '')
        AS col_timestamp,
    $19 AS col_tinyint,
    $20 AS col_tuple,
    $21 AS col_uuid,
    VARBINARY(IF($22 IS NULL, NULL,
        IF(LENGTH($22) % 2 = 1, CONCAT('0', $22), $22)))
        AS col_varbinary,
    $23 AS col_varchar;
```
:::

:::WorkflowBlockItem
Start the pipeline to load the data.&#x20;

```sql
START PIPELINE data_type_coverage_pipeline;
```

The sample data set can take about 30 seconds to fully load.&#x20;
:::

:::WorkflowBlockItem
Verify the `data_type_coverage` table is present.&#x20;

```shell
LIST TABLES;
```

Verify the row count in the table using this SQL statement.&#x20;

```sql
SELECT COUNT(*) FROM loading.data_type_coverage;
```

If the load operation is complete, the output table shows a count of about 100,000 rows.&#x20;

```none
count(*)
--------------------
100000

Fetched 1 row
```
:::

:::WorkflowBlockItem
When you are confident your data is fully loaded, you can delete the pipeline using the `DROP PIPELINE` SQL statement.&#x20;

```sql
DROP PIPELINE data_type_coverage_pipeline; 
```
:::
::::

Now that your Ocient simulator is loaded with data, you can add integrations for user interfaces, visualizations, and other applications. For details, see [Ocient Integrations](<./Connect to Ocient/Ocient Integrations.md>).&#x20;

# Container Configuration

This section explains the configuration setup and options for the Ocient simulator.&#x20;

## Ports

The container exposes additional ports that can be useful depending on the use case for the system.

| **Exposed Port** | **Description**                                                                    |
| ---------------- | ---------------------------------------------------------------------------------- |
| 4050             | The JDBC port of the cluster.                                                      |
| 8080             | Ocient LAT service. When you load new data, the LAT client connects to this port.  |
| 9090 and 9091    | The REST interfaces for the SQL and Foundation (LTS) Node processes, respectively. |

## Environment Variables

You can set these environment variables to affect certain aspects of the Ocient simulator.

| **Environment variable**            | **Description**                                                                                                                                                                                                                                                              |
| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| LAT\_MEMORY and LAT\_MEMORY\_DIRECT | Configures the memory used by LAT when it is running. For details about these environment variables, see the [LAT Service Configuration](<./LAT Reference/LAT Service Configuration.md>) page.<br />The LAT Node is the only node in the cluster affected by this variable.  |

**Example**

```yaml
services:
  lat:
    environment: 
      LAT_MEMORY: '32G'
```

## Resource Limits (CPU, Memory, Disk Usage)

Docker supports a variety of options to limit container access to host resources. Refer to the Docker [Runtime options with Memory, CPUs, and GPUs](https://docs.docker.com/config/containers/resource_constraints/) page for the full list of options. This section explains how constraints on specific host resources affect the Ocient simulator.

:::hint{type="info"}
In all of these code examples, replace `IMAGE` with the filename of your Docker image.
:::

:::hint{type="info"}
The Ocient System applies Docker resource configuration changes individually on each of the nodes in the `docker-compose.yml` file (such as `sql`, `foundation`, `loader`, `lat`). &#x20;
:::

### CPU

CPU can be safely limited without adverse effects. Most workloads benefit from having multiple CPU cores available (four or more).

For example, to add CPU limits to the `sql` node, add this text to the `docker-compose.yml` file in the simulator package. Replace the `'4'` with the CPU limit that you want.&#x20;

```yaml
services:
  sql:
    image: IMAGE
    deploy:
      resources:
        limits: 
          cpus: '4'
```

### Memory (RAM)

The Ocient simulator requires sufficient RAM to execute all workloads. The system can be unstable in low or out-of-memory conditions. If you need to limit the memory of the running Docker container, it is recommended to benchmark the container memory usage on your workload and provide at least 1GB of RAM above the maximum observed.

:::hint{type="warning"}
When limiting memory of the Ocient Simulator, do not use the `--oom-kill-disable` option, otherwise the database can become unresponsive for a significant period of time after running out of memory.
:::

To add memory limits to the `sql` node, add this text to the `docker-compose.yml` file in the simulator package. Replace the `8g` with the memory limit that you want.&#x20;

```yaml
services:
  sql:
    image: IMAGE
    deploy:
      resources:
        limits: 
          memory: 8g
```

### Disk Usage

When running the simulator without mounted data, you can specify the size in bytes of the data files created. The data files must be large enough to fit any data sets that you load. The file size defaults to 2GiB.&#x20;

To specify a different file size, you can configure the rolehostd startup command in the `docker-compose.yml` file. Add the command option `loopbackDeviceSize` with a new value to configure a new file size.&#x20;

In this example, the file size on the `foundation0` node is configured to 16GiB.&#x20;

```yaml
services:
  sql: 
    image: IMAGE
    command: "--bootstrap '{adminHost: \"sql\", ipAddress: \"foundation0\", loopbackDeviceSize: \"16GiB\"}}'" 
```

If you want to specify a new file size value, you must do it before you create your cluster. &#x20;

While you cannot resize files on a running cluster, you can change this value by deleting and recreating your cluster. This process is irreversible and erases any existing databases and tables. &#x20;

To resize file on an existing cluster:&#x20;

1. Stop your cluster by running `docker compose down`.
2. Clear the `volumes` directory by running `rm -rf volumes/`.&#x20;
3. If you have not yet edited the `docker-compose.yml` file, edit the file to include new `loopbackDeviceSize` values.&#x20;
4. Restart your cluster by running `docker compose up -d`.

## Simulator Logging

The Ocient simulator sends all logs to stdout and stderr as well as any logging driver configured for the host Docker installation or the container. This logging allows for easy inspection of container logs using the [`docker logs`](https://docs.docker.com/engine/reference/commandline/logs/) command.&#x20;

For details on logging with Docker, consult the [logging section](https://docs.docker.com/compose/compose-file/compose-file-v2/#logging) in the Docker documentation.&#x20;

### Setting Logging Levels

You can modify the logging level for each node in the cluster by configuring the `rolehostd` startup command in the `docker-compose.yml` file. Add the command option `logLevel` with a new log level.

Supported values include `error`, `info`, `warn`, `verbose`, or `debug`. Defaults to `info`.&#x20;

For details, see [Log Monitoring](<./System Administration/Monitoring/Log Monitoring.md>).&#x20;

**Example**

```yaml
services:
  sql: 
    image: IMAGE
    command: "--bootstrap '{adminHost: \"sql\", ipAddress: \"foundation0\", logLevel: \"debug\"}}'"
```

### Other Logging Configurations

You can customize your logging configuration for each node by making changes to the `docker-compose.yml` file. In this example, the `sql` node has special configurations for its `max-size` and `max-file` values, meaning the container should have no more than five log files of 10MB in size. &#x20;

**Example**

```yaml
services:
  sql: 
    image: IMAGE 
    logging:
      driver: json-file
      options:     
        max-size: 10m
        max-file: 5
```

Use `docker logs` to retrieve the logs. In this example, the `--tail` option limits the output to include only the last 10 lines of logs.&#x20;

For more options, see the [docker compose logs](https://docs.docker.com/engine/reference/commandline/compose_logs/) page.

```shell
docker logs --tail 10 CONTAINER
```

## Related Links

[Commands Supported by the Ocient JDBC CLI Program](<./Connection Driver Reference/JDBC Manual/Commands Supported by the Ocient JDBC CLI Program.md>)

[CREATE TABLE](<./SQL Reference/Data Definition Language _DDL_ Statement Reference/Tables.md>)&#x20;

***

**Linux®*&#x20;is the registered trademark of Linus Torvalds in the U.S. and other countries.*

