| Home | Libraries | People | FAQ | More

## Metadata

In the context of this library, metadata refers to information describing a column retrieved by the execution of a SQL query. The `metadata` class contains information about an individual column.

You may access metadata using `results::meta` or `execution_state::meta`. There is a `metadata` object per column retrieved by the query. The metadata objects are present even if no row was returned by the query (e.g. a `SELECT` on an empty table).

`connection` objects have an associated `metadata_mode` that describes how to handle metadata when running a query or a statement:

- If `connection::meta_mode` is `metadata_mode::minimal` (the default), the library will retain the minimal amount of data required to run the operation. Additional information, like column names, won't be retained. Unless you are using metadata explicitly, you should keep this default, as it consumes slightly less memory.
- If `connection::meta_mode` is `metadata_mode::full`, the library will retain all the information provided by the server, including column names.

Only the `metadata` members that are strings (database, table and field names) are affected by this setting. You may change this setting using `connection::set_meta_mode`.

For example:

    // By default, a connection has metadata_mode::minimal
    results result;
    conn.execute("SELECT 1 AS my_field", result);
    string_view colname = result.meta()[0].column_name();

    // colname will be empty because conn.meta_mode() == metadata_mode::minimal
    BOOST_TEST(colname == "");

    // If you are using metadata names, set the connection's metadata_mode
    conn.set_meta_mode(metadata_mode::full);
    conn.execute("SELECT 1 AS my_field", result);
    colname = result.meta()[0].column_name();
    BOOST_TEST(colname == "my_field");