mirror of
https://github.com/MariaDB/server.git
synced 2025-01-22 14:54:20 +01:00
116 lines
4 KiB
Text
116 lines
4 KiB
Text
@page
|
|
@section @code{DB->put}
|
|
@setfilename tokudb
|
|
@settitle DB->put
|
|
|
|
@c man title db_put tokudb
|
|
@unnumberedsubsec Synopsis
|
|
@c man begin SYNOPSIS
|
|
@code{#include <db.h>}
|
|
|
|
@code{int DB->put(DB *}@var{db}@code{, DB_TXN *}@var{txnid}@code{, DBT*}@var{key}@code{, DBT*}@var{data}@code{, u_int32_t }@var{flags}@code{);}
|
|
@c man end
|
|
|
|
@unnumberedsubsec Description
|
|
@c man begin DESCRIPTION
|
|
@code{DB->put} stores a key/data pair into a database, replacing any
|
|
previously existing key if duplicates are not enabled, or adding a
|
|
duplicate if sorted duplicates are enabled. (TokuDB does not support
|
|
unsorted duplicates, hence the new key-data pair is inserted at the
|
|
correct sorted location.)
|
|
|
|
Key items are limited to 16KB in size.
|
|
Data items are limited to 256KB in size (for now.)
|
|
@c man end
|
|
|
|
@unnumberedsubsec Parameters
|
|
@c man begin PARAMETERS
|
|
@table @var
|
|
@item db
|
|
The @code{DB} handle for the database.
|
|
@item txnid
|
|
Either @code{NULL} or a @code{TXNID}.
|
|
@item key
|
|
The key to be inserted.
|
|
@item data
|
|
The data to be inserted.
|
|
@item flags
|
|
Must be zero or must be one of the following flags. However, @code{flags} must be nonzero for sorted duplicates.
|
|
@table @code
|
|
@item 0
|
|
For non-dup databases, insert the new key/data pair, overwriting any pair with a matching key.
|
|
Zero is not allowed databases with duplicates (returns @code{EINVAL}).
|
|
|
|
@item DB_YESOVERWRITE
|
|
|
|
Insert the new key/data pair, overwriting any matching pair. If the
|
|
database supports sorted duplicates, then the matching key/data pair
|
|
(if any) is overwritten. If the database does not support duplicates,
|
|
then the pair with a matching key (if any) is overwritten. (TokuDB
|
|
supports only sorted duplicates, not unsorted duplicates.)
|
|
|
|
@item DB_NOOVERWRITE
|
|
Insert the new key/data pair only if the no key/data pair with a
|
|
matching key already exists in the database.
|
|
|
|
The @code{DB->put} function returns @code{DB_KEYEXIST} if
|
|
@code{DB_NOOVERWRITE} is set and the key already exists in the
|
|
database.
|
|
|
|
@item DB_NODUPDATA
|
|
Insert the new key/data pair only if it is not already present in the database.
|
|
|
|
@code{DB_NODUPDATA} may only be specifed when operating on databases that provide sorted duplicates.
|
|
|
|
The @code{DB->put} function returns @code{DB_KEYEXIST} if @code{DB_NODUPDATA} is set and the key/data pair is already present in the database.
|
|
|
|
Using @code{DB_NODUPDATA} can dramatically slow down deletions, since
|
|
it the implementation must perform a @code{DB->get} to determine
|
|
whether the pair already exists.
|
|
@end table
|
|
|
|
|
|
Rationale: Using @code{0} for flags does not give the results that
|
|
many users expect. The Berkeley DB documentation says that someday
|
|
they will support duplicate duplicates, and that if you want the
|
|
current behavior you should use @code{DB_NOOVERWRITE}. On the other
|
|
hand, the current behavior is very expensive, since it requires that
|
|
the implementation perform a @code{DB->get()}.
|
|
|
|
Further confounding issues that for Berkeley@tie{}DB has the following
|
|
behavior: For sorted duplicates, inserting the same pair twice returns
|
|
@code{DB_KEYEXIST}. For no-duplicates or unsorted duplicates,
|
|
inserting the same pair twice overwrites the pair returning @code{0}.
|
|
|
|
We wanted a mode in which matching data is overwritten, however
|
|
``matching'' is defined. Thus for non-duplicates, a matching pair is
|
|
one with the same key. For sorted duplicates, a matching pair is one
|
|
with the same key and data.
|
|
|
|
For high performance, use @code{DB_YESOVERWRITE}.
|
|
@end table
|
|
|
|
@c man end
|
|
@unnumberedsubsec Return Value
|
|
@c man begin RETURNVALUE
|
|
|
|
Returns zero on success. The following non-zero errors can be returned:
|
|
@table @code
|
|
@item DB_DEADLOCK
|
|
The system discovered deadlock cycle involving this and other transactions.
|
|
This operation was killed.
|
|
@item DB_LOCK_NOTGRANTED
|
|
In an environment configured for lock timeouts, the system was unable to grant a lock within the allowed time.
|
|
@item ENOENT
|
|
The file or directory does not exist.
|
|
@item EINVAL
|
|
You passed invalid parameters to this operation.
|
|
|
|
In particular, if you pass 0 to a database configured for duplicates,
|
|
then @code{DB->put()} returns @code{EINVAL}.
|
|
|
|
@end table
|
|
@c man end
|
|
|
|
@include everyman.texi
|
|
|