mirror of
https://github.com/MariaDB/server.git
synced 2025-01-22 14:54:20 +01:00
114 lines
4.1 KiB
Text
114 lines
4.1 KiB
Text
@page
|
|
@section @code{DB->del}
|
|
@setfilename tokudb
|
|
@settitle DB->del
|
|
|
|
@c man title db_del tokudb
|
|
@unnumberedsubsec Synopsis
|
|
@c man begin SYNOPSIS
|
|
@code{#include <db.h>}
|
|
|
|
@noindent
|
|
@code{int DB->del(DB *}@var{db}@code{, DB_TXN *}@var{txnid}@code{, DBT*}@var{key}@code{, u_int32_t }@var{flags}@code{);}
|
|
@c man end
|
|
@unnumberedsubsec Description
|
|
@c man begin DESCRIPTION
|
|
@code{DB->del}
|
|
removes all the key/data pairs that match @var{key}. If there are
|
|
duplicates, all matching records are removed.
|
|
|
|
When called on a secondary index (associated via
|
|
@code{DB->associate(3)}), all the matching keys in the secondary
|
|
database are used to identify keys/data pairs in the primary database.
|
|
The keys in the primary are all removed, and all the corresponding
|
|
records in all the secondary indices are removed.
|
|
|
|
@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 deleted.
|
|
@item flags
|
|
Must be zero or @code{DB_DELETE_ANY}.
|
|
Using @code{DB_DELETE_ANY} causes @code{DB->del()} to possibly return @code{0} even if
|
|
there are no matching key/data pairs.
|
|
|
|
Note: @code{DB_DELETE_ANY} is a Tokutek extension to the
|
|
Berkeley@tie{}DB API. A program developed for TokuDB can be used with Berkeley@tie{}DB by adding this to the code:
|
|
@example
|
|
#ifndef TOKUDB
|
|
#define DB_DELETE_ANY 0
|
|
#endif
|
|
@end example
|
|
|
|
@end table
|
|
|
|
@c man end
|
|
@unnumberedsubsec Return Value
|
|
@c man begin RETURNVALUE
|
|
Returns zero on success. Success is defined to be that either there
|
|
was at least one matching key/data pair and it was deleted, or there were zero or more
|
|
matching key/data pairs, and they were all deleted, and @code{BDB_DELETE_ANY} was passed.
|
|
|
|
The following non-zero values can be returned:
|
|
@table @code
|
|
@item DB_NOTFOUND
|
|
If the flags do not include @code{BDB_DELETE_ANY} and there was no
|
|
matching key/data pair, then @code{DB->del} returns @code{BDB_NOTFOUND}.
|
|
|
|
It is allowed for TokuDB to return @code{DB_NOTFOUND} even if
|
|
@code{BDB_DELETE_ANY} is specified. Using @code{DB_DELETE_ANY} means
|
|
that the caller does not care whether the result is @code{0} or
|
|
@code{DB_NOTFOUND}.
|
|
|
|
|
|
@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 EINVAL
|
|
You passed invalid parameters to this operation.
|
|
@end table
|
|
@c man end
|
|
|
|
@unnumberedsubsec Notes
|
|
@c man begin NOTES
|
|
|
|
Performing a deletion without @code{DB_DELETE_ANY} is relatively
|
|
expensive. For example, suppose you have a large database that is
|
|
stored on disk and is much larger than main memory. Then
|
|
@code{DB->get()} using a randomly selected key usually requires at
|
|
least one disk-head movement, limiting you about 100 to 150 get
|
|
operations per second per disk drive. A delete operation that doesn't
|
|
require the @code{DB_NOTFOUND} result to be computed can run much
|
|
faster, however (orders of magnitude faster in some cases.) For the
|
|
@code{DB->del} operation to compute the @code{DB_NOTFOUND} result
|
|
requires a get, which slows down the deletions.
|
|
|
|
However, suppose that the key you are deleting is already in main
|
|
memory (because you recently accessed it). In that case, there is
|
|
likely to be little or no performance difference between using
|
|
@code{DB_DELETE_ANY} or not.
|
|
|
|
Associated secondary indexes can also slow down deletion operations,
|
|
since TokuDB performs a @code{DB->get} to get the primary key/data pair
|
|
so that it can use the callback function to compute all the secondary
|
|
keys that must be deleted.
|
|
|
|
One way to achieve fast deletions with secondary indices is to design
|
|
your primary key so that contiguous ranges will be removed from your
|
|
database at the same time. For example, if you design your primary
|
|
key to be a timestamp, and you expire the oldest data first, then
|
|
deletions can run fast: Use a cursor to find the leftmost item, and
|
|
delete it, move right, delete some more, and so forth. The cursor
|
|
scan is fast, and the deletes on all the secondary keys will be fast
|
|
too.
|
|
@c man end
|
|
|
|
@include everyman.texi
|