Concepts

This pages explains the few concepts and characteristics involved in RacksDB databases.

Introduction

RacksDB is an object-oriented database organized in a tree layout. Objects are composed of set of named properties.

The various objects with their properties are defined in a schema.

Defining the content of the database basically consist of declaring objects in YAML files in conformity wtih the defined schema.

Objects

Objects are a set of named properties. Multiple types of objects are involved in the database, all with their respective set of properties. The various objects are defined in the schema.

Objects are declared as mappings (or hash tables) in the YAML files of the database. In these mappings, the keys are the name of the properties while the values are the values of the respective properties.

Properties

Properties have a name. Properties may have attributes that defines their characteritics. All properties also have a data type which can either be native or advanced. All these concepts are explained in the sections below.

Attributes

Properties may have various characteristics that are defined by their attributes. RacksDB supports the following attributes:

sequence: The property is list (or array) of values of the respective data type (ex: list of string or list of objects).

optional: The property is optional, its declaration for the respective objects is not required in the database.

default value: When the property is not declared for the respective objects in database, it is assigned this default value.

key

The property is a key for the respective objects. When the object is contained in a sequence, the value of this property can be used to refer to the object.

An object cannot be defined with more than one key property in the schema.

This is particularly useful to facilitate selection of a particular object among a list in the Python library.

Keys are also involved in sequence/mapping equivalence concept.

Types

Properties have a data type that defines how RacksDB interpret their values. Data types are either native or advanced.

Native types

RacksDB supports the following native types of properties:

str: Strings of characters.
int: Integer numbers.
float: Floating point numbers.
bool: Boolean value.

Advanced types

Beyond the native types, RacksDB supports a set of more advanced types:

object: The value is the declaration of another object.

reference

The value is a reference to another object attribute, declared elsewhere in the database.

If the given attribute value cannot be found among the corresponding declared objects, RacksDB considers this reference cannot be solved and raises an error while loading the database.

back reference

The value is a parent object or one of its attributes.

The back references type must not be defined in the database files. They are automatically defined and resolved by RacksDB when loading the database.

Back references are essentially used for convenience in the Python library.

defined type: The value is parsed by special bits of code provided by RacksDB, to match against special values or perform units conversions to convert them into native types. The defined types available in RackDB are described in the defined types section of the structure reference.

expandable: The value is a string representing a range of values that can be expanded into a list. For example, node[01-03,05] can be expanded into node01, node02, node03 and node05. For more details about this syntax, please refer to the documentation of ClusterShell nodeset command.

rangeid: The value is an integer number associated the first item of an expandable, automatically incremented for all the other items in the list.

The expandable and rangeid advanced types are notably used for automatic expansion of factorized range of objects.

Schema

The schema defines the structure of the database consisting of all objects with their properties in a tree layout.

The schema is defined in a YAML file. Objects with their attributes and types are defined with a dedicated syntax. It is possible to define schema extensions to enrich the database with custom data.

Automatic expansion

In order to significantly reduce boilerplate when declaring numerous consecutive objects, RacksDB is able to automatically expand factorized range of objects. For this purpose, two additional data types are used in the database:

As an example, consider an object with the following properties:

name of type expandable,
id of type rangeid.

And the following content in database file:

- name: node[01-03]
  id: 10

It is eventually expanded by RacksDB into this sequence:

- name: node01
  id: 10
- name: node02
  id: 11
- name: node03
  id: 12

Sequence/mapping equivalence

In RacksDB, a sequence (or list) of objects with a key property can alternatively be declared as a mapping (or hash table). In this case, the key of the mapping is considered as the value of the key property of the object.

As an example, consider an object Furniture with the following properties:

id of type str with key attribute,
description of type str
width of type int.

List of this object can be declared as a sequence in database YAML files:

- id: table
  description: table for dinner
  width: 180
- id: chair
  description: chair to sit
  width: 32

Alternatively, RacksDB offers the possibility to declared this list as a mapping in YAML files:

table:
  description: table for dinner
  width: 180
chair:
  description: chair to sit
  width: 32

This feature is particulary convenient to declare list of objects in a tree of splitted YAML files and use the filename as the value of the key property.