NAME

       WiredTiger - Getting Started with the API WiredTiger applications will generally use the
       following classes to access and manage data:

       • a WT_CONNECTION represents a connection to a database. Most applications will only open
         one connection to a database for each process. All methods in WT_CONNECTION are thread
         safe.

       • a WT_SESSION represents a context in which database operations are performed. Sessions
         are opened on a specified connection, and applications must open a single session for
         each thread accessing the database.

       • a WT_CURSOR represents a cursor over a collection of data. Cursors are opened in the
         context of a session (which may have an associated transaction), and can query and
         update records. In the common case, a cursor is used to access records in a table.
         However, cursors can be used on subsets of tables (such as a single column or a
         projection of multiple columns), as an interface to statistics, configuration data or
         application-specific data sources.

       Handles and operations are configured using strings, which keeps the set of methods in the
       API relatively small and makes the interface very similar regardless of the programming
       language used in the application. WiredTiger supports the C, C++, Java and Python
       programming languages (among others).

       By default, WiredTiger works as a traditional key/value store, where the keys and values
       are raw byte arrays accessed using a WT_ITEM structure. Keys and values may be up to (4GB
       - 512B) bytes in size, but depending on how WT_SESSION::create 'maximum item sizes' are
       configured, large key and value items will be stored on overflow pages.

       WiredTiger also supports a schema layer so that keys and values types can be chosen from a
       list, or composite keys or values made up of columns with any combination of types. The
       size (4GB - 512B) byte limit on keys and values still applies.

       All applications that use WiredTiger will be structured roughly as follows. The code below
       is taken from the complete example program ex_access.c.

Connecting to a database

       To access a database, first open a connection and create a session handle for the single
       thread accessing the database:

               WT_CONNECTION *conn;
               WT_CURSOR *cursor;
               WT_SESSION *session;
               const char *key, *value;
               int ret;

               /*
                * Create a clean test directory for this run of the test program if the
                * environment variable isn't already set (as is done by make check).
                */
               if (getenv("WIREDTIGER_HOME") == NULL) {
                       home = "WT_HOME";
                       ret = system("rm -rf WT_HOME && mkdir WT_HOME");
               } else
                       home = NULL;

               /* Open a connection to the database, creating it if necessary. */
               if ((ret = wiredtiger_open(home, NULL, "create", &conn)) != 0 ||
                   (ret = conn->open_session(conn, NULL, NULL, &session)) != 0) {
                       fprintf(stderr, "Error connecting to %s: %s0,
                           home, wiredtiger_strerror(ret));
                       return (ret);
               }

        The configuration string 'create' is passed to wiredtiger_open to indicate the database
       should be created if it does not already exist.

       The code block above also shows simple error handling with wiredtiger_strerror (a function
       that returns a string describing an error code passed as its argument). More complex error
       handling can be configured by passing an implementation of WT_EVENT_HANDLER to
       wiredtiger_open or WT_CONNECTION::open_session.

Creating a table

       Create a table we can use to store data:

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

        This call creates a table called 'access', configured to use strings for its key and
       value columns. (See Schema, Columns, Column Groups, Indices and Projections for more
       information on tables with other types of key and value columns.)

Accessing data with cursors

       Now that we have a table, we open a cursor to perform some operations on it:

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

        Here, the string 'table:access' specifies that we are opening the cursor on the table
       named 'access'.

       Then we insert a new row into the table. The WT_CURSOR::set_key and WT_CURSOR::set_value
       calls put the application's key and value into the cursor, respectively. The
       WT_CURSOR::insert call creates a record containing that value and inserts it into the
       table.

               cursor->set_key(cursor, "key1");        /* Insert a record. */
               cursor->set_value(cursor, "value1");
               ret = cursor->insert(cursor);

        Now we iterate through all of the records in the table, printing them out as we go:

               ret = cursor->reset(cursor);            /* Restart the scan. */
               while ((ret = cursor->next(cursor)) == 0) {
                       ret = cursor->get_key(cursor, &key);
                       ret = cursor->get_value(cursor, &value);

                       printf("Got record: %s : %s0, key, value);
               }

        Note that the key and value parts of the records are returned as C strings because the
       table was created that way (even if it was created by a previous run of the example). No
       data extraction or conversion is required in the application.

       Because the cursor was positioned in the table after the WT_CURSOR::insert call, we had to
       re-position it using the WT_CURSOR::first call; if we weren't using the cursor for the
       call to WT_CURSOR::insert above, this loop would simplify to:

       while ((ret = cursor->next(cursor)) == 0) {
               ...
       }

Closing handles

       Lastly, we close the connection, which implicitly closes the cursor and session handles:

               ret = conn->close(conn, NULL);