.. _model-repository-and-storing:

*********************************
Model repository and model stores
*********************************

Overview
--------

A model store can be used to persist trained pgx machine learning models (see :ref:`MLib overview <ml-lib-graph>`) along with a model name (a unique identifier of the model in this particular model store) and a description. 

The model repository provides the API to

- list all available model stores in the model repository,

- create new and delete existing model stores,

- list all models in a given model store,

- get the model description for a model that is stored in the given model store,

- delete a model from the given model store.

Multiple model stores can coexist next to each other (e.g. one for each user or one for dev, staging and production).

DB backed model repository
--------------------------

In a db backed model repository, each model store corresponds to a table in the database. Internally, the tables are 
prefixed by ``GMLS_``.

The following code block illustrates the usage of the model repository api and shows how 

- a model store can be created
  
- the existing model stores can be listed

- a model can be persisted in a model store along with a name and a description
  
- models stored in a model store can be listed
  
- a model can be loaded from the model store
  
- the description of a stored model can be retrieved from a model store
  
- a model can be deleted from a model store

- a model store can be deleted

.. code-block:: python
    :linenos:

    username = 'username'
    password = 'password'
    modelstore = 'modelstore'
    modelname = 'deepwalk_model'
    jdbc_url = 'jdbc:oracle:thin:@localhost:1521:rdbmsod'
    model_description = 'some description'
    # create a db backed model repository object
    mr = analyst.model_repository().db(
        # DB user to use for storing the model
        username=username,
        # password of the DB user
        password=password,
        # jdbc url to the DB
        jdbc_url=jdbc_url
    )

    # list model stores
    mr.list_model_stores_names()

    # create a model store
    mr.create("modelstore")

    # list model stores and see that there are no models yet
    mr.list_model_stores_names()
    mr.list_model_stores_names_matching("modelstore")
    mr.list_models("modelstore")

    # create and fit a model
    model = analyst.deepwalk_builder(
        window_size=3,
        walks_per_vertex=6,
        walk_length=4
    )
    model.fit(small_graph)

    model.export().db(
        # name of the model store table
        modelstore,
        # name to give to the model (primary key of model store table)
        modelname,
        # DB user to use for storing the model
        username=username,
        # password of the DB user
        password=password,
        # jdbc url to the DB
        jdbc_url=jdbc_url,
        # description to store alongside the model
        model_description=model_description,
        overwrite=True
    )

    # verify that the model is now stored in the model store
    mr.list_models(modelstore)

    # load the model from the model store
    analyst.get_deepwalk_model_loader().db(
        username="user",
        password="password",
        model_store="modelstore",
        model_name="deepwalk_model",
        jdbc_url="jdbc_url"
    )

    # get the model description for the model
    mr.get_model_description("modelstore", "deepwalk_model")
    # delete the model from the model store
    mr.delete_model("modelstore", "deepwalk_model")
    # delete the whole model store
    mr.delete_model_store("modelstore")


File backed model repository
----------------------------

The model repository api is currently not supported for file based model persistence.