@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