.. _ConfigFile:

Configuration File
==================

ApertureDB uses a configuration file (following a JSON format)
that can be specified when starting the server using the "-cfg" flag:

    ./aperturedb -cfg config.json

If no configuration file is specified, ApertureDB will try to open the
default file (config.json), and will fail to initiate if the file is not found.

Parameters
----------

All the parameters in the configuration file are optional,
as ApertureDB has default values for all of them:

.. list-table::
   :widths: 20 20 20
   :header-rows: 1

   * - Parameter
     - Explanation
     - Default
   * - port
     - TCP port for incoming connections
     - 55555
   * - max_simultaneous_clients
     - Number of max simultaneous connections open
     - 500
   * - db_root_path
     - Path to the root folder where all filed/objects will be stored
     - db
   * - images_path
     - Path to folder where images (all formats) will be stored
     - images (db/images)
   * - blobs_path
     - Path to folder where blobs will be stored
     - blobs (db/blobs)
   * - descriptors_path
     - Path to folder where descriptors will be stored
     - descriptors (db/descriptors)
   * - create_parameters
     - Object used to specify parameters used at creation time
     - N/A
   * - create_parameters["pmgd_num_allocators"]
     - Number of allocators when creating a new PMGD graph (this will only be
       used  * - when creating a new graph, and ignored if the graph already exist)
     - 1
   * - create_parameters["pmgd_max_strlen"]
     - Maximum length of strings for class and properties name
     - 64
   * - create_parameters["pmgd_node_size"]
     - Size of the Node representation in memory, in bytes
     - 64
   * - create_parameters["pmgd_edge_size"]
     - Size of the Edge representation in memory, in bytes
     - 32
   * - create_parameters["pmgd_txtable_size"]
     - Size of transaction (TX) table in KB. Determines max concurrent TXs.
     - 4
   * - create_parameters["pmgd_journal_size"]
     - Total in-memory journal space for all TXs, in MB. Determines space per TX.
     - 128
   * - log_path
     - Directory where logs will be placed.
     - "/tmp"
   * - log_level
     - Levels INFO, WARNING, ERROR, and FATAL are 0, 1, 2, and 3, respectively.
     - 1 (WARNING)
   * - verbose_log_level
     - Verbosity level beyond INFO, for debugging. Will set log_level = 0.
       Check Google glog documentation for details.
     - -1 (no verbosity beyond INFO)
   * - log_cerr_threshold
     - Specify level of logging which will also be sent to stderr
     - 3 (FATAL)
   * - collect_thread_interval
     - Number of seconds between collecting system status information.
     - 1
   * - collect_interval_set
     - An array of look-back intervals, in seconds,
       over which system status information is averaged.
     - [5,10,30,120]
   * - query_retry_count
     - Timed-out query will be retried that many times or until it succeeds, whichever comes first.
     - 30
   * - resources_check_sleep
     - Number of seconds between resource utilization checks.
     - 2
   * - resources_check_mem_limit
     - Limit on percentage of memory utilization after which queries are stopped.
     - 93

Config File Example
-------------------

Here is an example configuration file that has all the parameters
with its default values.
There is no need to specify any parameter if you want to work with
default values.

.. code-block:: python

    // ApertureDB Config File
    // All parameters show the default values.
    {
        // Network
        "port": 55555,
        "max_simultaneous_clients": 500,
        "max_connection_message_size_mb": 256,

        // DB paths
        "db_root_path":     "db",
        "blobs_path":       "db/blobs",
        "images_path":      "db/images",
        "videos_path":      "db/videos",
        "descriptors_path": "db/descriptors",

        // Log parameters
        "log_path":           "/tmp/",
        "log_level":          1,        // Warnings only
        "verbose_log_level":  0,
        "log_cerr_threshold": 3,

        // Batching parameters
        "batch_cleaner_interval":  10,
        "batch_time_to_live":      60,

        // Resource Check  parameters
        "resources_check_sleep":     2,
        "resources_check_mem_limit": 93,

        // Telemetry collection parameters
        "collect_thread_interval": 1,
        "collect_interval_set":   [5,10,30,120]

        // Timed-out queries
        "query_retry_count: 32,

        // Parameters used only when creating a new db
        "create_parameters": {

            "pmgd_num_allocators": 1,
            "pmgd_max_strlen":     64,
            "pmgd_node_size":      64,
            "pmgd_edge_size":      32,
            "pmgd_locale_name":    ""
        },

        "index": [
            {
                "index_type":"entity",
                "class":"Sample",
                "property_key":"mixed_sample_id",
                "property_type":"string"
            },
            {
                "index_type":"entity",
                "class":"Sample",
                "property_key":"sample_id",
                "property_type":"string"
            }
        ],

        "more-info": "ApertureDB"
    }

Default Directories Structure
-----------------------------

By default, ApertureDB will create a directory structure as follows:

.. code-block:: console

    db
    ├── blobs
    ├── descriptors
    ├── graph
    └── images
        ├── jpg
        ├── png
        └── tdb
    └── videos