Configuration Strings

Introduction

Methods in WiredTiger take a configuration string to provide optional arguments and configure non-standard behaviors. These strings are simple comma-separated lists of "<key>=<value>" pairs, and all have the same format:

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

Keys and values and values that consist of alphanumeric characters can be specified directly. More precisely, keys or values that match this regular expression do not require quotes:

    [-_0-9A-Za-z/][^\t\r\n :=,\])}]*

More complex keys and values can be specified by quoting them with double quotes.

For example, a configuration string is used when opening a connection to a database to specify if the database should be created and to set the cache size:

        ret = wiredtiger_open(home, NULL, "create,cache_size=500M", &conn);

Configuration strings are also used to configure the table schema. For example, to create a table that uses C language strings for keys and values:

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

To handle more complex schema configuration, such as specifying multiple columns in a table, values are nested using parentheses. For example:

        /*
         * Create a table with columns: keys are record numbers, values are
         * (string, signed 32-bit integer, unsigned 16-bit integer).
         */
        ret = session->create(session, "table:mytable",
            "key_format=r,value_format=SiH,"
            "columns=(id,department,salary,year-started)");

All types of parentheses are treated equivalently by the parser.

When an integer values is expected, the value may have multiplier characters appended, as follows:

Character	Meaning	Change to value
B or b	byte	no change
K or k	kilobyte	multiply by 2^10
M or m	megabyte	multiply by 2^20
G or g	gigabyte	multiply by 2^30
T or t	terabyte	multiply by 2^40
P or p	petabyte	multiply by 2^50

For example, the value 500B is the same as entering the number 500, the value 500K is the same as 512000 and the string 500GB is the same as 536870912000.

Values of type of "boolean" can be set to any of false, true, 0 or 1. If no value is specified for a key, the value 1 is implied. For example, all of the following forms of the overwrite configuration string are identical:

        ret = session->open_cursor(session, "table:mytable", NULL,
            "overwrite", &cursor);
        ret = session->open_cursor(session, "table:mytable", NULL,
            "overwrite=true", &cursor);
        ret = session->open_cursor(session, "table:mytable", NULL,
            "overwrite=1", &cursor);

Configuration strings are processed in order from left to right, with later settings overriding earlier ones (unless multiple settings for a key are supported by the method).

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.

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

JavaScript Object Notation (JSON) compatibility

WiredTiger configuration strings are compatible with JavaScript Object Notation (JSON), and 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"]
})

Because JSON compatibility allows colons to be used as key/value separators, WiredTiger URIs may require quoting. For example, the following WT_SESSION::checkpoint call specifies a set of URIs as checkpoint targets, using double-quote characters to keep the parser from treating the colon characters as JSON name/value separators:

        /*
         * Checkpoint a list of objects.
         * JSON parsing requires quoting the list of target URIs.
         */
        ret = session->
            checkpoint(session, "target=(\"table:table1\",\"table:table2\")");