1 files changed, 126 insertions, 0 deletions
diff --git a/src/third_party/wiredtiger/src/docs/basic-api.dox b/src/third_party/wiredtiger/src/docs/basic-api.dox
new file mode 100644
index 00000000000..2b810e6676b
--- /dev/null
+++ b/src/third_party/wiredtiger/src/docs/basic-api.dox
@@ -0,0 +1,126 @@
+/*! @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
+
+ */