mongo/src/docs/basic-api.dox

/*! @m_page{{c,java},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
keys and values are
@m_if{c}
raw byte arrays accessed using a WT_ITEM structure.
@m_else
raw byte arrays.
@m_endif
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 @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 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_ref{ex_access.c}.

@section basic_connection Connecting to a database

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

@snippet ex_access.c access example connection

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

@m_if{c}
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.
@m_endif
@m_if{java}
The code block above also shows simple error handling by catching
WiredTigerException.
@m_endif

@section basic_create_table Creating a table

Create a table we can use to store data:

@snippet ex_access.c access example table create

This call creates a table called @c "access", configured to use strings
for its key and value columns.  (See @ref schema for more information
on tables with other types of key and value columns.)

@section basic_cursors Accessing data with cursors

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

@snippet ex_access.c access example cursor open

Here, the string @c "table:access" specifies that we are opening the
cursor on the table named @c "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.

@snippet ex_access.c access example cursor insert

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

@snippet ex_access.c access example cursor list

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:

@snippet ex_access.c access example close

 */