Datastore Configuration

The datastore consists of a collection of stores that can be linked together through references. This page introduces the concepts you need to know when working with the datastore and walks you through setting up a basic datastore from a datastore description.

Stores

A store is a collection of records that share the same attributes, called the fields (or columns) of the store. In a standard database, a store is similar to a table, and records similar to rows.

Store Description

All stores are built according to a store description, represented by the interface IStoreDescription. When building a reference description, we recommend using the builder interface available through StartBuilding.store(). The builder provides a fluent API to specify the field structure of a store. The following snippet defines the description of a Product store including information about products sold by a retailer:

final IStoreDescription productStoreDescription =
    StartBuilding.store()
        .withStoreName("Product")
        .withField("id", ILiteralType.LONG)
        .asKeyField()
        .withField("category", ILiteralType.STRING, "uncategorized")
        .withNullableField("name", ILiteralType.STRING)
        .withVectorField("priceHistory", ILiteralType.DOUBLE)
        .build();

Field Specification

Store fields are specified by:

a name
a data type, from the values contained in the ILiteralType interface

Both scalar types and vector types are supported as field types.

.withField("id", ILiteralType.LONG)
.withVectorField("priceHistory", ILiteralType.DOUBLE)

Default Values

A default value may be specified during field declaration. Otherwise, a default value is selected based on the data type: 0 for numerical types and the string "N/A" for most object types. A field may also be declared nullable, meaning that no default value is used for the field, accepting null as a value instead.

.withField("category", ILiteralType.STRING, "uncategorized")
.withNullableField("name", ILiteralType.STRING)

Key Fields

Any number of fields in a store can be flagged as key fields through:

.withField("id", ILiteralType.LONG)
.asKeyField()

The set of key fields in a store should uniquely identify each record in the store. A key field can be made nullable. You can build a keyless store using .withoutKey() after all fields have been specified, although such stores are restricted regarding possible operations, due to the lack of key.

References

The different stores within a datastore can be linked together through references. A reference is a mapping from one store (the owner store) to another store (the target store), associating one or more fields of the former to fields of the latter. Each reference defines a many-to-one relationship between two stores. They are useful at query time to relate the information from different stores together. A datastore generally has a multitude of references, forming a directed graph of stores. The store graph cannot contain any cycle: the schema of stores can also be referred to as a star schema, as it has a tree-like structure. A store can reference another one multiple times, as long as the referenced fields are different for the multiple references.

Constraints

When a reference is created between two stores, a uniqueness constraint is added to the group of fields used by the reference in the target store. As such, a line of the base store cannot point to multiple lines of the target store. This is a consequence of the many-to-one relationship represented by the reference. For example, given two stores A and B:

Store A
TradeId Value
Trade1 10
Trade2 20
Store B
TradeId LegType Book
Trade1 N/A Book1
Trade2 N/A Book2
Trade3 Pay Book3
Trade3 Recv Book3

TradeId	Value
Trade1	10
Trade2	20

TradeId	LegType	Book
Trade1	N/A	Book1
Trade2	N/A	Book2
Trade3	Pay	Book3
Trade3	Recv	Book3

If we define a reference from Store A’s TradeId field to Store B’s TradeId field, a KeyConstraintViolationException is raised when Store B is loaded, because multiple lines in Store B share the same TradeId.

Reference Description

Similarly to stores, datastore references are built according to a reference description, represented by the interface IReferenceDescription. When building a reference description, we recommend using the fluent builder interface available through StartBuilding.reference(). A fully defined reference description is created like so:

final IReferenceDescription referenceDescription =
    StartBuilding.reference()
        .fromStore("store A")
        .toStore("targetStore B")
        .withName("AToB")
        .withMapping("field from A", "field from B")
        .withMapping("another field from A", " another field from B")
        .build();

Example

In this example, the required datastore consists of two stores:

Sale: records correspond to a product sale.
PriceHistory: records define the product prices at certain dates.

final IStoreDescription saleStoreDescription =
    StartBuilding.store()
        .withStoreName("Sale")
        .withField("id", ILiteralType.LONG)
        .asKeyField()
        .withField("productId", ILiteralType.LONG)
        .asKeyField()
        .withField("date", ILiteralType.DATE)
        .asKeyField()
        .withField("quantity", ILiteralType.INT)
        .withField("unitPrice", ILiteralType.DOUBLE)
        .build();
final IStoreDescription priceHistoryStoreDescription =
    StartBuilding.store()
        .withStoreName("Product")
        .withField("id", ILiteralType.LONG)
        .asKeyField()
        .withField("name", ILiteralType.STRING)
        .withField("category", ILiteralType.STRING, "uncategorized")
        .build();

The following reference associates the product information from the Product store to the sales of the Sale store, using the product ID as mapping.

final IReferenceDescription referenceDescription =
    StartBuilding.reference()
        .fromStore("Sale")
        .toStore("Product")
        .withName("SaleToProduct")
        .withMapping("productId", "id")
        .build();

Datastore Schema

A datastore is built according to a datastore schema, which gathers the store descriptions and the reference descriptions that compose the datastore. When building a datastore schema, we recommend using the fluent builder interface available through StartBuilding.datastoreSchema():

final IDatastoreSchemaDescription datastoreSchemaDescription =
    StartBuilding.datastoreSchema()
        .withStore(saleStoreDescription)
        .withStore(priceHistoryStoreDescription)
        .withReference(referenceDescription)
        .build();

The .withStore() and .withReference() methods can be chained as many times as needed.

Creating a Datastore

Once the datastore schema has been created, the datastore can be built using StartBuilding.application():

final var application =
    StartBuilding.application()
        .withDatastore(datastoreSchemaDescription)
        .withoutBranchRestrictions()
        .build();
final IDatastore datastore = application.getDatastore();

The IDatastore interface implements AutoCloseable, and can be torn down using the close() method.

Querying a Datastore

Data can be retrieved directly from the datastore using Database Queries.

Introduction

Getting started

Concepts

Step 1: Getting your data into Atoti

Step 2: Designing your cube

Step 3: Access your data with front ends or custom clients

Configure Atoti Options

Set up security and entitlements for Atoti

Monitoring and running Atoti Server

Release & Migration Notes

Reference

Datastore Configuration

Stores

Store Description

Field Specification

Default Values

Key Fields

References

Constraints

Reference Description

Example

Datastore Schema

Creating a Datastore

Querying a Datastore

​Stores

​Store Description

​Field Specification

​Default Values

​Key Fields

​References

​Constraints

​Reference Description

​Example

​Datastore Schema

​Creating a Datastore

​Querying a Datastore

Stores

Store Description

Field Specification

Default Values

Key Fields

References

Constraints

Reference Description

Example

Datastore Schema

Creating a Datastore

Querying a Datastore