=encoding utf8

=head1 NAME

Apache::Solr::JSON - Apache Solr (Lucene) client via JSON

=head1 INHERITANCE

 Apache::Solr::JSON
   is an Apache::Solr

=head1 SYNOPSIS

  my $solr = Apache::Solr::JSON->new(...);
  my $solr = Apache::Solr->new(format => 'JSON', ...);

=head1 DESCRIPTION

Implement the Solr client, where the communication is in JSON.

Both the requests and the responses are using JSON syntax, produced by
the JSON distribution (which defaults to JSON::XS when installed)

B<Warning 1:>
Apparently, Perl's JSON implementation does not support the repetition
of keys in one list, but Solr is using that.  Care is taken to avoid
these cases.

B<Warning 2:>
In some cases, XML and JSON differ in structure and names in the structure.
In those cases, the XML plan is made leading: the JSON data is transformed
to match the XML.

Extends L<"DESCRIPTION" in Apache::Solr|Apache::Solr/"DESCRIPTION">.

=head1 METHODS

Extends L<"METHODS" in Apache::Solr|Apache::Solr/"METHODS">.

=head2 Constructors

Extends L<"Constructors" in Apache::Solr|Apache::Solr/"Constructors">.

=over 4

=item $class-E<gt>B<new>(%options)

Inherited, see L<Apache::Solr/"Constructors">

 -Option            --Defined in     --Default
  agent               Apache::Solr     <created internally>
  autocommit          Apache::Solr     true
  core                Apache::Solr     undef
  field_key_simplify  Apache::Solr     true
  format              Apache::Solr     'JSON'
  json                                 <created internally>
  retry_max           Apache::Solr     60
  retry_wait          Apache::Solr     5
  server              Apache::Solr     <required>
  server_version      Apache::Solr     <latest>

=over 2

=item agent => LWP::UserAgent-object

=item autocommit => BOOLEAN

=item core => $name

=item field_key_simplify => BOOLEAN

=item format => 'XML'|'JSON'

=item json => JSON object

By default, an JSON object is created for you, in utf8 mode.

=item retry_max => COUNT

=item retry_wait => $seconds

=item server => $url

=item server_version => $version

=back

=back

=head2 Attributes

Extends L<"Attributes" in Apache::Solr|Apache::Solr/"Attributes">.

=over 4

=item $obj-E<gt>B<agent>()

Inherited, see L<Apache::Solr/"Attributes">

=item $obj-E<gt>B<autocommit>( [BOOLEAN] )

Inherited, see L<Apache::Solr/"Attributes">

=item $obj-E<gt>B<core>( [$core] )

Inherited, see L<Apache::Solr/"Attributes">

=item $obj-E<gt>B<fieldKeySimplify>()

Inherited, see L<Apache::Solr/"Attributes">

=item $obj-E<gt>B<json>()

Z<>

=item $obj-E<gt>B<server>( [$uri|STRING] )

Inherited, see L<Apache::Solr/"Attributes">

=item $obj-E<gt>B<serverVersion>()

Inherited, see L<Apache::Solr/"Attributes">

=back

=head2 Commands

See L<https://wiki.apache.org/solr/UpdateJSON>

Extends L<"Commands" in Apache::Solr|Apache::Solr/"Commands">.

=head3 Search

Extends L<"Search" in Apache::Solr|Apache::Solr/"Search">.

=over 4

=item $obj-E<gt>B<queryTerms>($terms)

Inherited, see L<Apache::Solr/"Search">

=item $obj-E<gt>B<select>( [\%options], @parameters )

Inherited, see L<Apache::Solr/"Search">

=back

=head3 Updates

Extends L<"Updates" in Apache::Solr|Apache::Solr/"Updates">.

=over 4

=item $obj-E<gt>B<addDocument>($doc|\@docs, %options)

Inherited, see L<Apache::Solr/"Updates">

 -Option            --Defined in     --Default
  allowDups           Apache::Solr     false
  commit              Apache::Solr     <autocommit>
  commitWithin        Apache::Solr     undef
  overwrite           Apache::Solr     true
  overwriteCommitted  Apache::Solr     <not allowDups>
  overwritePending    Apache::Solr     <not allowDups>

=over 2

=item allowDups => BOOLEAN

=item commit => BOOLEAN

=item commitWithin => $seconds

=item overwrite => BOOLEAN

=item overwriteCommitted => BOOLEAN

=item overwritePending => BOOLEAN

=back

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

Inherited, see L<Apache::Solr/"Updates">

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

Inherited, see L<Apache::Solr/"Updates">

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

Inherited, see L<Apache::Solr/"Updates">

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

Inherited, see L<Apache::Solr/"Updates">

=item $obj-E<gt>B<rollback>()

Inherited, see L<Apache::Solr/"Updates">

=back

=head3 Core management

Extends L<"Core management" in Apache::Solr|Apache::Solr/"Core management">.

=over 4

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

Inherited, see L<Apache::Solr/"Core management">

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

Inherited, see L<Apache::Solr/"Core management">

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

Inherited, see L<Apache::Solr/"Core management">

=back

=head2 Helpers

Extends L<"Helpers" in Apache::Solr|Apache::Solr/"Helpers">.

=over 4

=item $obj-E<gt>B<decodeResponse>($response)

Z<>

=item $obj-E<gt>B<simpleDocument>( $command, [$attributes, [$content]] )

Construct a simple XML structure.

=item $obj-E<gt>B<simpleUpdate>( $command, $attributes, [$content] )

Z<>

=back

=head1 DETAILS

Extends L<"DETAILS" in Apache::Solr|Apache::Solr/"DETAILS">.

=head1 DIAGNOSTICS

=over 4

=item Fault: Cannot read document from $fn: $!

Cast by C<extractDocument()>

=item Fault: Read error for document $fn: $!

Cast by C<extractDocument()>

=item Fault: Solr request failed after $elapse seconds after $retries retries: $!

Cast by C<request()>

=item Alert: Solr request failed with $code, $retries retries left: $!

Cast by C<request()>

=item Error: Solr request failed with: $err

Cast by C<request()>

=item Error: Solr version too old for updates in JSON syntax.

Cast by C<addDocument()>

=item Error: Solr version too old for updates in JSON syntax.

Cast by C<simpleUpdate()>

=item Error: answer from solr server is not json but $type.

Cast by C<decodeResponse()>

=item Warning: deprecated solr $message

Cast by C<deprecated()>

=item Error: extract requires document as file or string.

Cast by C<extractDocument()>

=item Error: extractDocument() requires Solr v1.4 or higher.

Cast by C<extractDocument()>

=item Error: field $field is not simple for a set.

Cast by C<expandSelect()>

=item Warning: ignored solr $message

Cast by C<ignored()>

=item Warning: removed solr $message

Cast by C<removed()>

=item Error: rollback not supported by your solr server version.

Cast by C<rollback()>

=item Error: set $set cannot be used per field, in $field.

Cast by C<expandSelect()>

=item Error: unable to add more than one doc with JSON interface.

Cast by C<addDocument()>

=item Error: unknown field set $set.

Cast by C<expandSelect()>

=back

=head1 SEE ALSO

This module is part of Apache-Solr version 1.12,
built on July 15, 2026. Website: F<https://perl.overmeer.net/CPAN/>

=head1 LICENSE

For contributors see file ChangeLog.

This software is copyright (c) 2012-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.

