Couch-DB/lib/Couch/DB/Design.pod
=encoding utf8
=head1 NAME
Couch::DB::Design - handle design documents
=head1 INHERITANCE
Couch::DB::Design
is a Couch::DB::Document
=head1 SYNOPSIS
my $ddoc = Couch::DB::Design->new(id => 'myname', db => $db);
my $ddoc = $db->design('myname'); # same
my $ddoc = $db->design('_design/myname'); # same
my $ddoc = $db->design; # id generated
my $results = $db->design('d')->search('i', ...) or die;
my $results = $db->search(d => 'i', ...); # same
my $results = $db->search($ddoc => 'i', ...); # same
=head1 DESCRIPTION
In CouchDB, design documents provide the main interface for building
a CouchDB application. The design document defines the views used to
extract information from CouchDB through one or more views.
Design documents behave just like your own documents, but occupy the
C<_design/> namespace in your database. A bunch of the methods are
therefore exactly the same as the methods in base-class
L<Couch::DB::Document|Couch::DB::Document>.
Extends L<"DESCRIPTION" in Couch::DB::Document|Couch::DB::Document/"DESCRIPTION">.
=head1 METHODS
Extends L<"METHODS" in Couch::DB::Document|Couch::DB::Document/"METHODS">.
=head2 Constructors
Extends L<"Constructors" in Couch::DB::Document|Couch::DB::Document/"Constructors">.
=over 4
=item Couch::DB::Design-E<gt>B<fromResult>($result, $data, %options)
Inherited, see L<Couch::DB::Document/"Constructors">
=item Couch::DB::Design-E<gt>B<new>(%options)
If no id is passed, then one gets generated: a UUID is requested from
the server. You may also use a local generator via UUID::URandom
or Data::UUID, which is (of course) more efficient.
-Option --Defined in --Default
batch Couch::DB::Document from database
content Couch::DB::Document undef
db Couch::DB::Document undef
id Couch::DB::Document generated
local Couch::DB::Document false
row Couch::DB::Document undef
=over 2
=item batch => BOOLEAN
=item content => DATA
=item db => L<Couch::DB::Database|Couch::DB::Database>-object
=item id => ID
=item local => BOOLEAN
=item row => L<Couch::DB::Row|Couch::DB::Row>-object
=back
=back
=head2 Accessors
Extends L<"Accessors" in Couch::DB::Document|Couch::DB::Document/"Accessors">.
=over 4
=item $obj-E<gt>B<batch>()
Inherited, see L<Couch::DB::Document/"Accessors">
=item $obj-E<gt>B<couch>()
Inherited, see L<Couch::DB::Document/"Accessors">
=item $obj-E<gt>B<db>()
Inherited, see L<Couch::DB::Document/"Accessors">
=item $obj-E<gt>B<id>()
Inherited, see L<Couch::DB::Document/"Accessors">
=item $obj-E<gt>B<idBase>()
Various calls need the C<id> without the C<_design>. Whether the
full document id for the design document or only the unique part
is required/given is confusing. This method returns the unique
part.
=item $obj-E<gt>B<row>( [$row] )
Inherited, see L<Couch::DB::Document/"Accessors">
=item Couch::DB::Design-E<gt>B<setIdGenerator>(CODE)
When a design document is created without explicit C<id>, that will
get generated. By default, this is done by requesting a fresh UUID
from the server. You may change this into some local random collission
free id generator for better performance.
The CODE is called with the daabase object as only parameter.
=back
=head2 Content
Extends L<"Content" in Couch::DB::Document|Couch::DB::Document/"Content">.
=over 4
=item $obj-E<gt>B<isDeleted>()
Inherited, see L<Couch::DB::Document/"Content">
=item $obj-E<gt>B<isLocal>()
Inherited, see L<Couch::DB::Document/"Content">
=item $obj-E<gt>B<latest>()
Inherited, see L<Couch::DB::Document/"Content">
=item $obj-E<gt>B<rev>()
Inherited, see L<Couch::DB::Document/"Content">
=item $obj-E<gt>B<revision>($rev)
Inherited, see L<Couch::DB::Document/"Content">
=item $obj-E<gt>B<revisions>()
Inherited, see L<Couch::DB::Document/"Content">
=back
=head2 Document details
Extends L<"Document details" in Couch::DB::Document|Couch::DB::Document/"Document details">.
=over 4
=item $obj-E<gt>B<conflicts>()
Inherited, see L<Couch::DB::Document/"Document details">
=item $obj-E<gt>B<deletedConflicts>()
Inherited, see L<Couch::DB::Document/"Document details">
=item $obj-E<gt>B<revisionInfo>($revision)
Inherited, see L<Couch::DB::Document/"Document details">
=item $obj-E<gt>B<revisionsInfo>()
Inherited, see L<Couch::DB::Document/"Document details">
=item $obj-E<gt>B<updateSequence>()
Inherited, see L<Couch::DB::Document/"Document details">
=back
=head2 Document in the database
All methods below are inherited from standard documents. Their call URI
differs, but their implementation is the same. On the other hand: they
add interpretation on fields which do not start with '_'.
Extends L<"Document in the database" in Couch::DB::Document|Couch::DB::Document/"Document in the database">.
=over 4
=item $obj-E<gt>B<appendTo>($doc, %options)
[CouchDB API "COPY /{db}/_design/{ddoc}"]
=item $obj-E<gt>B<cloneInto>($doc, %options)
[CouchDB API "COPY /{db}/_design/{ddoc}"]
=item $obj-E<gt>B<create>(\%data, %options)
[CouchDB API "POST /{db}/_index", UNTESTED]
Create a new design document.
In Couch::DB, the client-side, not the server, generates ids. Therefore,
this method is equivalent to L<update()|Couch::DB::Design/"Document in the database">.
-Option--Defined in --Default
batch Couch::DB::Document new(batch)
=over 2
=item batch => BOOLEAN
=back
=item $obj-E<gt>B<delete>(%options)
[CouchDB API "DELETE /{db}/_design/{ddoc}"]
=item $obj-E<gt>B<details>(%options)
[CouchDB API "GET /{db}/_design/{ddoc}/_info", UNTESTED]
Obtains information about the specified design document, including the
index, index size and current status of the design document and associated
index information.
=item $obj-E<gt>B<exists>(%option)
[CouchDB API "HEAD /{db}/_design/{ddoc}"]
Returns the HTTP Headers containing a minimal amount of information about the
specified design document.
=item $obj-E<gt>B<get>(%options)
[CouchDB API "GET /{db}/_design/{ddoc}"]
=item $obj-E<gt>B<update>(\%data, %options)
[CouchDB API "PUT /{db}/_design/{ddoc}"]
Options C<filters>, C<lists>, C<shows>, and C<updates> are HASHes which
map names to fragments of code written in programming language C<language>
(usually erlang or javascript).
Options C<lists>, C<show>, and C<rewrites> (query redirection) are
deprecated since 3.0, and are removed from 4.0.
-Option--Defined in --Default
batch Couch::DB::Document new(batch)
=over 2
=item batch => BOOLEAN
=back
=back
=head2 Attachments
Extends L<"Attachments" in Couch::DB::Document|Couch::DB::Document/"Attachments">.
=over 4
=item $obj-E<gt>B<attDelete>($name, %options)
[CouchDB API "DELETE /{db}/_design/{ddoc}/{attname}" ]
=item $obj-E<gt>B<attExists>($name, %options)
[CouchDB API "HEAD /{db}/_design/{ddoc}/{attname}"]
=item $obj-E<gt>B<attInfo>($name)
Inherited, see L<Couch::DB::Document/"Attachments">
=item $obj-E<gt>B<attLoad>($name, %options)
[CouchDB API "GET /{db}/_design/{ddoc}/{attname}" ]
=item $obj-E<gt>B<attSave>($name, $data, %options)
[CouchDB API "PUT /{db}/_design/{ddoc}/{attname}" ]
-Option--Defined in --Default
type Couch::DB::Document application/octet-stream
=over 2
=item type => IANA-MediaType
=back
=item $obj-E<gt>B<attachment>($name)
Inherited, see L<Couch::DB::Document/"Attachments">
=item $obj-E<gt>B<attachments>()
Inherited, see L<Couch::DB::Document/"Attachments">
=back
=head2 Indexes (indices)
=over 4
=item $obj-E<gt>B<createIndex>(\%config, %options)
[CouchDB API "POST /{db}/_index", UNTESTED]
Create an index on the database. If the name already exists and the
configuration is different, then the index be get regenerated.
=item $obj-E<gt>B<deleteIndex>($index, %options)
[CouchDB API "DELETE /{db}/_index/{designdoc}/json/{name}", UNTESTED]
Remove an index from this design document.
=item $obj-E<gt>B<indexDetails>($index, %options)
[CouchDB API "GET /{db}/_design/{ddoc}/_search_info/{index}", UNTESTED]
Returns metadata for the specified search index.
=item $obj-E<gt>B<search>( $index, [\%search, %options] )
[CouchDB API "GET /{db}/_design/{ddoc}/_search/{index}", UNTESTED]
Executes a (text) search request against the named $index. The default
C<%search> contains the whole index. When the search contains
C<include_docs>, then full docs are made available.
(Of course) this command supports paging.
example: return full index all as rows
my $d = $db->design('d');
my $rows = $d->search('i', {}, all => 1)->page;
my $search = +{ include_docs => 1 };
my @docs = $d->search('i', \%search, all => 1)->pageDocs;
=back
=head2 Views
=over 4
=item $obj-E<gt>B<viewDocs>( $view, [\%search|\@%search], %options] )
[CouchDB API "GET /{db}/_design/{ddoc}/_view/{view}", UNTESTED]
[CouchDB API "POST /{db}/_design/{ddoc}/_view/{view}", UNTESTED]
[CouchDB API "POST /{db}/_design/{ddoc}/_view/{view}/queries", UNTESTED]
[CouchDB API "GET /{db}/_partition/{partition}/_design/{ddoc}/_view/{view}", UNTESTED]
Executes the specified view function.
This work is handled in L<Couch::DB::Database::allDocs()|Couch::DB::Database/"Handling documents">. See that method for
C<%options> and results.
example:
my %search;
my $c = $db->design('people')->viewDocs(customers => \%search, all => 1);
my $hits = $c->page;
my %search = (design => 'people', view => 'customers');
my $c = $db->allDocs(\%search, all => 1);
=back
=head2 Functions
=over 4
=item $obj-E<gt>B<applyUpdate>( $function, [$doc|$docid|undef, %options] )
[CouchDB API "POST /{db}/_design/{ddoc}/_update/{func}", UNTESTED]
[CouchDB API "POST /{db}/_design/{ddoc}/_update/{func}/{docid}", UNTESTED]
See what the update function would change. The update C<$function> is run
on a document, specified by id or object. By default or explicit undef,
a C<null> (missing) document will be used.
=item $obj-E<gt>B<list>($function, $view, %options)
[CouchDB API "GET /{db}/_design/{ddoc}/_list/{func}/{view}", deprecated 3.0, removed 4.0, UNTESTED]
[CouchDB API "POST /{db}/_design/{ddoc}/_list/{func}/{view}", deprecated 3.0, removed 4.0, UNTESTED]
[CouchDB API "GET /{db}/_design/{ddoc}/_list/{func}/{other-ddoc}/{view}", deprecated 3.0, removed 4.0, UNTESTED]
[CouchDB API "POST /{db}/_design/{ddoc}/_list/{func}/{other-ddoc}/{view}", deprecated 3.0, removed 4.0, UNTESTED]
Executes a list function against the C<$view>.
-Option --Default
view_ddoc undef
=over 2
=item view_ddoc => $ddoc|$ddocid
When the C<$view> resides in a different design.
=back
=item $obj-E<gt>B<show>( $function, [$doc|$docid|undef, %options] )
[CouchDB API "GET /{db}/_design/{ddoc}/_show/{func}", deprecated 3.0, removed 4.0, UNTESTED]
[CouchDB API "POST /{db}/_design/{ddoc}/_show/{func}", deprecated 3.0, removed 4.0, UNTESTED]
[CouchDB API "GET /{db}/_design/{ddoc}/_show/{func}/{docid}", deprecated 3.0, removed 4.0, UNTESTED]
[CouchDB API "POST /{db}/_design/{ddoc}/_show/{func}/{docid}", deprecated 3.0, removed 4.0, UNTESTED]
Apply show C<$function> on the document, as specified by C<$docid> or document object. By
default or explicit C<undef>, a "null" document will be used.
=back
=head1 SEE ALSO
This module is part of Couch-DB distribution version 0.200,
built on June 18, 2025. Website: F<http://perl.overmeer.net/CPAN/>
=head1 LICENSE
Copyrights 2024-2025 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 F<http://dev.perl.org/licenses/>