.. _modify-schema:

Modify Feature Vector Database Structure
===========================================

Sometimes it may be necessary to apply a new structural schema to your Tarantool-based feature vector database, for example, when updating to the latest version of the product, or when you want to enhance the default database structure with additional parameters, advanced object metadata, and so on.

.. rubric:: In this section:

.. contents::
   :local:

About Database Structure
------------------------------

In FindFace Multi, the database structure is set via the ``/etc/findface-security/tnt_schema.lua`` file.

The structure is created as a set of fields. Each field is described with the following parameters:

* id: field id;
* name: field name, must be the same as the name of a relevant object parameter;
* field_type: data type;
* default: field default value. If a default value exceeds ‘1e14 – 1', use a string data type to specify it, for example, ``"123123.."`` instead of ``123123..``.

You can find the default ``tnt_schema.lua`` file :download:`here <_scripts/tnt_schema.lua.txt>`.


Structure Modification
--------------------------------


To modify the database structure, do the following:

#. Stop the ``findface-security`` service.

   .. code::

      sudo systemctl stop findface-security.service

#. Create a backup of the Tarantool-based feature vector database in any directory of your choice, for example, ``/etc/findface_dump``. 

   .. tip::
      See :ref:`backup-restore` for details.
 
   .. code::

      mkdir -p /etc/findface_dump
      cd /etc/findface_dump
      sudo findface-storage-api-dump -config /etc/findface-sf-api.ini

#. Prepare the ``tnt_schema.lua`` file containing the new database structure. 
#. Modify the database structure by applying the new ``tnt_schema.lua`` file.
 
   .. code::

      sudo findface-security make_tnt_schema | sudo tee /etc/findface-security/tnt_schema.lua

#. Navigate to the directory with Tarantool configuration file(s) ``/etc/tarantool/instances.available/``. For each shard, make sure that there is a line ``dofile("/etc/findface-security/tnt_schema.lua")`` before the ``FindFace.start`` section and ``meta_scheme`` and ``meta_indexes`` are defined in the ``FindFace.start`` parameters.     

   .. code::

      sudo vi /etc/tarantool/instances.available/<shard_00N>.lua

      dofile("/etc/findface-security/tnt_schema.lua") 
      
      FindFace.start("127.0.0.1", 8101, {
          license_ntls_server="127.0.0.1:3133",
          meta_indexes=meta_indexes,
          meta_scheme = meta_scheme
      })
 
#. Purge data from all the directories relevant to active shards.
 
   .. code::

      sudo rm /opt/ntech/var/lib/tarantool/shard-*/{index,snapshots,xlogs}/*

#. Restore the Tarantool database from the backup.

   .. important::
      If some fields were removed from the new database structure, you have to first manually delete the corresponding data from the backup copy.  
 
   .. code::

      cd /tmp/dump
      for x in *.json; do curl -X POST "http://127.0.0.1:18411/v2/galleries/${x%%.json}"; done
      for x in *.json; do sudo findface-storage-api-restore -config /etc/findface-sf-api.ini < "$x"; done

#. Start the ``findface-security`` service.

   .. code::

      sudo systemctl start findface-security.service


.. seealso::
   :ref:`custom-metadata`