Configuration Strings

Introduction

Many operations in WiredTiger accept a string to configure options. These strings all have the same format:

  [key['='value]][','[key['='value]]]*

That is, they are simple comma-separated lists of "<key>=<value>" pairs. If the "=<value>" part is omitted, the value of 1 is assumed.

To handle more complex configuration, such as specifying a schema, values may be nested lists using parentheses. For example:

  schema=(keyfmt=S,valuefmt=S,columns=(name,notes))

Empty configuration strings may be represented in C or C++ by passing NULL.

Superfluous commas and whitespace in the configuration string are ignored (including at the beginning and end of the string), so it is always safe to combine two configuration strings by concatenating them with a comma in between.

Keys are processed in order from left to right, with later settings overriding earlier ones unless multiple settings for a key are permitted.

JSON compatibility

The parser for configuration strings will accept additional formatting as follows:

• parentheses may be round or square brackets or curly braces: '()', '[]' or '{}'
• the whole configuration string may optionally be wrapped in parentheses
• the key/value separator can be a colon: ':'
• keys and values may be in double quotes: "key" = "value"
• quoted strings are interpreted as UTF-8 values

The result of this relaxed parsing is that applications may pass strings representing valid JSON objects wherever configuration strings are required.

For example, in Python, code might look as follows:

import json
config = json.dumps({
    "key_format" : "r",
    "value_format" : "5sHQ",
    "columns" : ("id", "country", "year", "population"),
    "colgroup.population" : ["population"],
    "index.country_year" : ["country", "year"]
})

Code samples

Open a connection to a database, creating it if it does not exist and set a cache size of 10MB, then open a session in the database:

        if ((ret = wiredtiger_open(home, NULL,
            "create,cache_size=500M", &conn)) != 0)
                fprintf(stderr, "Error connecting to %s: %s\n",
                    home, wiredtiger_strerror(ret));

Create a table that uses C language strings for keys and values:

        ret = conn->open_session(conn, NULL, NULL, &session);

        ret = session->create(session,
            "table:access", "key_format=S,value_format=S");

Walk a transactional cursor through the table:

        ret = session->begin_transaction(session, "priority=100,name=mytxn");

        ret = session->open_cursor(session, "config:", NULL, NULL, &cursor);

        while ((ret = cursor->next(cursor)) == 0) {
                cursor->get_key(cursor, &key);
                cursor->get_value(cursor, &value);
                printf("configuration value: %s = %s\n", key, value);
        }

        ret = session->commit_transaction(session, NULL);