Dictionary - metadata

GdaMetaStore — Dictionary object
GdaMetaStruct — In memory representation of some database objects

Each connection has a dictionary object (a GdaMetaStore) attached to it. That dictionary is either created by the connection when it needs it, or is created and set by the user (to be able to re-use a dictionary), using the "meta-store" property of the GdaConnection object.

Previous versions of libgda used an XML file based dictionary which had several drawbacks (see the migrations notes for more details), now a database is used: the default is to use an SQLite base database which is easily transportable and can be used in the same way the previous XML based dictionary was used.

Each GdaMetaStore requires (and creates) a dictionary structure which is a set of tables implementing an "information schema" schema (as defined in the information schema SQL standard (ISO/IEC 9075), and adapted). The user is then free to add more database objects (tables and views) to contain his own data in the dictionary, using the gda_meta_store_schema_add_custom_object() method.

Extracting information can be done using SQL statements on the dictionary database (a special gda_meta_store_extract() method), or, for information about the database structure, using the GdaMetaStruct object which creates an easy to use in-memory representation of some database objects.

GdaConnection and GdaMetaStore setups

Each GdaMetaStore object internally uses a (private) GdaConnection connection object. The following figure illustrates the situation when the programmer uses a GdaConnection connection object when the meta data is stored in a different database (usually an SQLite file):

GdaConnection object and its associated GdaMetaStore using its own database to store the meta data.

From a programmer's point of view, the following code example shows how to get a connection's associated meta store object, without being able to specify anything about the meta store's private connection (in which case the private connection will be an in-memory database destroyed when the meta store object is destroyed):

GdaConnection *cnc;
GdaMetaStore *store;

cnc = gda_connection_open_from_dsn (...);
g_object_get (G_OBJECT (cnc), "meta-store", &store, NULL);

[... use the meta store object ...]
g_object_unref (store);
	  

One can also specify the meta store object to be used by a connection, as in:

GdaConnection *cnc;
GdaMetaStore *store;

cnc = gda_connection_open_from_dsn (...);
store = gda_meta_store_new_with_file ("/path/to/file");
/* or */
store = gda_meta_store_new ("PostgreSQL://DB_NAME=meta_db");

g_object_set (G_OBJECT (cnc), "meta-store", store, NULL);
g_object_unref (store);
	  

The meta data can also be stored in the same database as the connection the meta data is for. In this case (and if the associated database provider supports it), the dictionary structure can be placed into a spearate schema. The next figure illustrates this situation:

GdaConnection object and its associated GdaMetaStore using the same database.

From a programmer's point of view, the following code example shows how to do the setup:

GdaConnection *cnc;
GdaMetaStore *store;

cnc = gda_connection_open_from_dsn (...);
store = GDA_META_STORE (GDA_TYPE_META_STORE, "cnc", cnc, NULL);
g_object_set (G_OBJECT (cnc), "meta-store", store, NULL);
g_object_unref (store);
	  

How to store custom data in a GdaMetaStore

This section explains how to add application specific data to a #GdaMetaStore object.

Applications of course don't need to use that feature to manage their own data but it makes sense to use it if the application also uses metadata to avoid having to manipulate several files for the same "task".

Storing data as (key, value) pairs

In very simple cases, when the data to store is made of named values, the easiest way is to use the gda_meta_store_set_attribute_value() and gda_meta_store_get_attribute_value() methods where the values are stored and retreived as strings.

Declaring the new custom database objects

Adding and removing data

Removing custom database objects