=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 $class-E<gt>B<fromResult>($result, $data, %options)

Inherited, see L<Couch::DB::Document/"Constructors">

=item $class-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 $class-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 C<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}"]
Improves base, see L<Couch::DB::Document/"Document in the database">

=item $obj-E<gt>B<cloneInto>($doc, %options)

  [CouchDB API "COPY /{db}/_design/{ddoc}"]
Improves base, see L<Couch::DB::Document/"Document in the database">

=item $obj-E<gt>B<create>(\%data, %options)

  [CouchDB API "POST /{db}/_index", UNTESTED]
Create a new design document.

In L<Couch::DB|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">.
Improves base, see L<Couch::DB::Document/"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}"]
Improves base, see L<Couch::DB::Document/"Document in the database">

=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.
Improves base, see L<Couch::DB::Document/"Document in the database">

=item $obj-E<gt>B<get>(%options)

  [CouchDB API "GET /{db}/_design/{ddoc}"]
Improves base, see L<Couch::DB::Document/"Document in the database">

=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.
Improves base, see L<Couch::DB::Document/"Document in the database">

 -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}" ]
Improves base, see L<Couch::DB::Document/"Attachments">

=item $obj-E<gt>B<attExists>($name, %options)

  [CouchDB API "HEAD /{db}/_design/{ddoc}/{attname}"]
Improves base, see L<Couch::DB::Document/"Attachments">

=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}" ]
Improves base, see L<Couch::DB::Document/"Attachments">

=item $obj-E<gt>B<attSave>($name, $data, %options)

  [CouchDB API "PUT /{db}/_design/{ddoc}/{attname}" ]
Improves base, see L<Couch::DB::Document/"Attachments">

 -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/{design_doc}/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 C<$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<compactViews>(%options)

  [CouchDB API "POST /{db}/_compact/{ddoc}", UNTESTED]

Start the compacting (optimization) of all views in this design document.
See L<Couch::DB::Database::compactViews()|Couch::DB::Database/"Database information"> to start them for all design
documents at once.

=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_id}/_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 C<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 DIAGNOSTICS

=over 4

=item Warning: -hex

Cast by C<revisions()>

=item Error: you have requested the open_revs detail for the document yet.

Cast by C<revisionsInfo()>

=back

=head1 SEE ALSO

This module is part of Couch-DB version 0.201,
built on January 30, 2026. Website: F<http://perl.overmeer.net/CPAN/>

=head1 LICENSE

For contributors see file ChangeLog.

This software is copyright (c) 2024-2026 by Mark Overmeer.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

