mongo/docs/src/basic-api.dox

/*! @page basic_api 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 @ref config_strings "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
key and value are raw byte arrays accessed with WT_ITEM.  Keys can be up to
4GB, but depending on how @ref WT_SESSION::create "page sizes" are
configured, keys larger than some size will be stored on overflow pages.  

WiredTiger also supports a @ref schema "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 4GB limit on keys and values
still applies.

@dontinclude ex_access.c

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

@section basic_connection Connecting to a database

To access a database, first open a connection with the following code:
@skip main
@until Note

Here the configuration string @c "create" is passed to ::wiredtiger_open to
indicate that the database should be created if it does not already exist.

Next we open a session handle for the single thread accessing the database.

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_ERROR_HANDLER to
wiredtiger_open or WT_CONNECTION::open_session.

@section basic_create_table Creating a Table

If the database was created by the ::wiredtiger_open call above, it will be
empty.  We now create a table that we can use to store data:

@until ;

This call creates a table called @c "access", configured to use strings for
its key and value columns.  We go into more details about what is possible
later in the section on @ref schema.

@section basic_cursors Accessing Data With Cursors

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

@until insert

Here, the string @c "table:access" specifies that we are opening the cursor
on the table named @c "access" that we created above.

The WT_CURSOR::set_key and WT_CURSOR::set_value calls put the application's
data into the cursor.  The WT_CURSOR::insert call creates a record
containing that data and inserts it into the table.

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

@until }

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:

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

@section basic_close Closing Handles

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

@skipline close
 */