The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Couch-DB-0.001
River stage zero No dependents
/ Couch::DB::Document

NAME

Couch::DB::Document - one document as exchanged with a CouchDB server

SYNOPSIS

  my $doc = $couch->db($dbname)->doc($docid);
  my $doc = $db->doc->create(\%data);
  my $doc = $db->doc($id, local => 1);

  my $content = $db->latest;

DESCRIPTION

This class manages one document, without understanding the payload. When exchanging questions and answers with the server, keys which start with an underscore (_) may get added and removed: they should not be visible in your data.

METHODS

Constructors

Couch::DB::Document->new(%options)
 -Option--Default
  batch   from database
  db      undef
  id      undef
  local   false
batch => BOOLEAN

For all of the writes which support it, use batch (no wait) writing. Of course, this may cause data to be lost when technical or logical issues emerge while the actual writing is done, but is much faster.

db => Couch::DB::Database-object

If this document is database related.

id => ID

When you are creating a new document (create()), you may leave this open to get an id generated. Otherwise, this parameter is required.

local => BOOLEAN

Use a local document: do not replicate it to other instances. Only limited actions are permitted on local documents... probably they do not support attachments.

Accessors

$obj->batch()
$obj->couch()
$obj->db()
$obj->id()

Content

Warning: Where Perl does not support the same data-types as JSON, you need to be very careful when addressing fields from this structure. Much better is it to use the provided abstraction methods, which hide those differences. Those also hide changes in the server software, over time.

$obj->isDeleted()

Returns a boolean whether the document is delete.

$obj->isLocal()

This documents does not get replicated over nodes.

$obj->latest()

Returns the data of the latest revision of the document, as retreived by any former call on this document object.

$obj->rev()

The latest revision of this document.

$obj->revision($rev)

Returns the data for document revision $rev, if retreived by a former call.

$obj->revisions()

Returns a sorted list of all known revisions, as retreived by a former call. They are sorted, newest first.

Document details

These methods usually require a get() with sufficient parameters to be useable (they die on unsuffient details).

$obj->conflicts()

Returns a LIST with conflict details.

$obj->deletedConflicts()

Returns a LIST with deletedConflict details.

$obj->revisionInfo($revision)

Returns a HASH with information about one $revision only.

$obj->revisionsInfo()

Returns a HASH with all revisions and their status.

$obj->updateSequence()

Returns the update sequence code for this document on the current server (local_seq). Only useful when you use an explicit _client when you get() the document.

Document in the database

All CouchDB API calls documented below, support %options like _delay and on_error. See "Using the CouchDB API" in Couch::DB.

$obj->appendTo($doc, %options)
 [CouchDB API "COPY /{db}/{docid}", PARTIAL]
 [CouchDB API "COPY /{db}/_local/{docid}", PARTIAL]
See also L<cloneInto()|Couch::DB::Document/"Document in the database">.

As %options: batch and rev.

example: appending one document into an other

   my $from = $db->doc('from');
   $from->get or die;
   my $to   = $db->doc('to');   # does not exist
   $to->get or die;
   $from->appendTo($to) or die;
$obj->cloneInto($doc, %options)
 [CouchDB API "COPY /{db}/{docid}", PARTIAL]
 [CouchDB API "COPY /{db}/_local/{docid}", PARTIAL]
See also L<appendTo()|Couch::DB::Document/"Document in the database">.

As %options, batch and rev.

example: cloning one document into a new one

   my $from = $db->doc('from');
   $from->get or die;
   my $to   = $db->doc('to');   # does not exist
   $from->cloneInto($to) or die;
$obj->create(\%data, %options)
 [CouchDB API "POST /{db}"]
Save this document for the first time to the database. Your content of the
document is in %data.  When you pick your own document ids, you can also use
L<update()|Couch::DB::Document/"Document in the database"> for a first save.

 -Option--Default
  batch   new(batch)
batch => BOOLEAN

Do not wait for the write action to be completed.

$obj->delete(%options)
 [CouchDB API "DELETE /{db}/{docid}"]
 [CouchDB API "DELETE /{db}/_local/{docid}"]
Flag the document to be deleted.  A new revision is created, which reflects this.
Only later, when all replications know it and compaction is run, the document
versions will disappear.
$obj->exists(%option)
 [CouchDB API "HEAD /{db}/{docid}"]
Check whether the document exists.  You may get some useful response headers.

example:

  if($db->doc($id)->exists) { ... }
$obj->get(%options)
 [CouchDB API "GET /{db}/{docid}"]
 [CouchDB API "GET /{db}/_local/{docid}"]
Retrieve document data and information from the database.  There are a zillion
of %options to collect additional meta-data.

When no explicit revision (option rev) is given, then the latest revision is collected.

Returned is, as usual, whether the database gave a successful response. The data received will get merged into this object's attributes.

example: use of get()

  my $game = $db->doc('monopoly');
  $game->get(latest => 1) or die;
  my $data = $game->latest;
$obj->update(\%data, %options)
 [CouchDB API "PUT /{db}/{docid}"]
 [CouchDB API "PUT /{db}/_local/{docid}"]
Save a new revision of this document to the database.  If docid is new,
then it will be created, otherwise a new revision is added.  Your content
of the document is in %data.

When you want to create a new document, where the servers creates the id, then use create().

 -Option--Default
  batch   new(batch)
batch => BOOLEAN

Do not wait for the write action to be completed.

Attachments

$obj->attDelete($name, %options)
 [CouchDB API "DELETE /{db}/{docid}/{attname}", UNTESTED]
$obj->attExists($name, %options)
 [CouchDB API "HEAD /{db}/{docid}/{attname}", UNTESTED]
The response is empty, but contains some useful headers.
$obj->attInfo($name)

Return a structure with meta-data about the attachments.

$obj->attLoad($name, %options)
 [CouchDB API "GET /{db}/{docid}/{attname}", UNTESTED]
Load the data of the attachment into this Document.

If the content-type of the attachment is application/octet-stream, then you can use the Accept-Ranges header (option _header) to select bytes inside the attachement.

$obj->attSave($name, $data, %options)
 [CouchDB API "PUT /{db}/{docid}/{attname}", UNTESTED]

The data is bytes.

 -Option--Default
  type    application/octet-stream
type => IANA-MediaType

For text documents, this may contain a charset like text/plain; charset="utf-8".

$obj->attachment($name)

Returns the bytes of the named attachment (of course, you need to get it first).

$obj->attachments()

Returns the names of all attachments.

SEE ALSO

This module is part of Couch-DB distribution version 0.001, built on May 29, 2024. Website: http://perl.overmeer.net/CPAN/

LICENSE

Copyrights 2024 by [Mark Overmeer]. For other contributors see ChangeLog.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See http://dev.perl.org/licenses/