> ## Documentation Index
> Fetch the complete documentation index at: https://docs.activeviam.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting started

This section explains how to get started using DirectQuery to connect to an external Database.

<Tip>
  For an overview of DirectQuery, see the [DirectQuery Overview](../../getting-started/directquery) section in the User Guide.
</Tip>

To connect to a remote Database using DirectQuery you need to complete these steps:

1. Configure your remote Database in Atoti Market Risk's expected [Database format](../../database)
2. Set the Atoti Market Risk configuration properties
3. Deploy Atoti Market Risk in Horizontal Distribution

## Database schema

Your remote Database must be configured in the same format as Atoti Market Risk's in-memory datastores. This means the same Tables and Field Types will need to be replicated.
You can do this by defining the Tables as outlined in the [Database](../../database) documentation or by exposing Views on your Database in the
same expected [Database](../../database) format.

<Note>
  All of the Database Tables must be present either as actual Tables or Views on your connected Database.
</Note>

## DirectQuery properties

The following properties must be configured to get started with DirectQuery.

### Profiles

The application provides [Spring profiles](../../properties/profiles) for each natively [supported database](./configuration-getting-started/supported-databases).
These profiles contain the properties to start Atoti Market Risk in DirectQuery mode and connect to the database.
You can find these profiles in the `mr-application/src/main/resources/` directory:

* [application-databricks.yaml](../../properties/profiles/application-databricks-yaml)
* [application-mssql.yaml](../../properties/profiles/application-mssql-yaml)
* [application-snowflake.yaml](../../properties/profiles/application-snowflake-yaml)

You can use these profiles as a starting point for your own configuration.

### Deployment type

You must set the deployment type to `direct-query` for Atoti Market Risk to run as a DirectQuery application.

```yaml theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
starter:
  deployment:
    type: direct-query
```

This property is already set in the [provided profiles](#profiles).

### Disable summary cubes

The Atoti Market Risk summary cubes aren’t supported when using DirectQuery. You must disable them from the configuration file by setting those properties:

```yaml theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
mr:
  enable:
    cubes:
      var-summary: false
      pnl-summary: false
      sensi-summary: false
```

These properties are already set in the [provided profiles](#profiles).

### Database-specific properties

The [provided profiles](#profiles) are a good starting point to configure your Atoti Market Risk DirectQuery application.
For specific environments and use-cases, you may need to adjust some of these properties. There are also additional properties not included in the profiles.
See [DirectQuery properties](../../properties/config-properties/directquery) for the full list of properties.

## Deployment options

We provide two main options to run with DirectQuery:

<table><thead><tr><th>Option</th><th>How to run Atoti Market Risk</th></tr></thead><tbody><tr><td>Operate with some data loaded in-memory and the rest available through DirectQuery</td><td>In <a class="highlight" href="#horizontal-distribution">Horizontal Distribution with in-memory Database</a></td></tr><tr><td>Run purely on DirectQuery remote data</td><td>In a <a class="highlight" href="#single-jvm">Single JVM</a> on DirectQuery only</td></tr></tbody></table>

### Horizontal distribution

In Horizontal Distribution you have access to the in-memory tools such as What-If, data updates and Sign-Off for the data loaded in-memory as well as
access to a large number of historical dates.

When running in Horizontal Distribution you need to run three Nodes:

* Query node
* In-memory data node
* DirectQuery data node

#### Query node

The query node is responsible for handling all queries from the client and coordinating with the data nodes to retrieve the required data.

Activate the [dist-query-node](../../properties/profiles/application-dist-query-node-yaml) Spring [profile](../../properties/profiles) to start the application in query node mode.

#### In-memory data node

The in-memory data node stores recent data in-memory and efficiently handles queries that can be answered from this in-memory data.

Activate the [dist-data-node](../../properties/profiles/application-dist-data-node-yaml) Spring [profile](../../properties/profiles) to start the application in data node mode.

#### DirectQuery data node

The DirectQuery data node handles queries that need to be answered from the external database.

Select the profile corresponding to your database from the [provided profiles](#profiles) to start the application in DirectQuery data node mode. You also
need to set the following property to enable communication with the query node:

```yaml theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
starter:
  deployment:
    transport: netty
```

#### Ports

By default, Atoti Market Risk runs on port 10010. If you are running multiple nodes on the same machine, you need to change the port for each node.
You can do this by setting the following property `server.port` property, providing a different value for each node.

#### Dates

It’s likely that your database and your in-memory data node may contain overlapping dates. This requires
[special handling](./customization-and-internals/dates-to-include) in a horizontally distributed setup.

#### Sign-Off

Sign-Off is not supported with DirectQuery but, using horizontal distribution, you can create a cluster in which there is a DirectQuery data node and an
in-memory data node for which Sign-Off features are enabled. For details on this setup, see [Adjustments in the DirectQuery database.](./customization-and-internals/adjustments-in-dq-database).

### Single JVM

You can run a single JVM consisting of only DirectQuery. This will not contain any in-memory data.

#### Properties

To run the Single JVM node, you only need to configure the [DirectQuery properties](#required-directquery-properties) and run the application as normal.
There are no distributed nodes to configure when running in a single JVM.

#### Single JVM limitations

Running DirectQuery with a single JVM means you are running purely on DirectQuery. This comes at the compromise of query performance of Trade-level queries and also
doesn’t have access to in-memory only tools (such as What-If and Sign-Off).

<Note>
  Running both an in-memory data node and DirectQuery data node under a single JVM isn’t supported.
</Note>

## Reference database

Databricks
MSSQL
Snowflake

Atoti Market Risk ships with the SQL scripts and data needed to initialize a Databricks database that can be used for testing. The scripts and reference data are
located within the directory: `mr-directquery/src/test/resources/databases/databricks/`.

Atoti Market Risk ships with an example MSSQL database that can be used for testing. This database runs inside a Docker container.
It is located within the directory: `mr-directquery/src/test/resources/databases/mssql/`.

Atoti Market Risk ships with the SQL and data needed to initialize a Snowflake database that can be used for testing. The SQL scrip is located within the
directory: `mr-directquery/src/test/resources/databases/snowflake/`. The reference data can be found in the `mr-application/src/main/resources/data/` directory.