Skip to content

Commit 7337062

Browse files
Copilotepugh
Copilot
and
epugh
committed
Add indexing-with-v2-apis.adoc documenting V2 update API endpoints
Co-authored-by: epugh <22395+epugh@users.noreply.github.com>
1 parent 4d2cbc0 commit 7337062

File tree

3 files changed

+188
-1
lines changed

3 files changed

+188
-1
lines changed

‎solr/solr-ref-guide/modules/indexing-guide/indexing-nav.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,7 @@
5050
* Indexing & Data Operations
5151
** xref:indexing-with-update-handlers.adoc[]
5252
*** xref:transforming-and-indexing-custom-json.adoc[]
53+
*** xref:indexing-with-v2-apis.adoc[]
5354
** xref:indexing-with-cbor.adoc[]
5455
** xref:indexing-with-tika.adoc[]
5556
** xref:indexing-nested-documents.adoc[]

‎solr/solr-ref-guide/modules/indexing-guide/pages/indexing-with-update-handlers.adoc‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
= Indexing with Update Handlers
2-
:page-children: transforming-and-indexing-custom-json
2+
:page-children: transforming-and-indexing-custom-json, indexing-with-v2-apis
33
// Licensed to the Apache Software Foundation (ASF) under one
44
// or more contributor license agreements. See the NOTICE file
55
// distributed with this work for additional information
@@ -20,6 +20,9 @@
2020
Update handlers are request handlers designed to add, delete and update documents to the index.
2121
In addition to having plugins for importing rich documents (see xref:indexing-with-tika.adoc[]), Solr natively supports indexing structured documents in XML, CSV, and JSON.
2222

23+
NOTE: Solr also exposes update functionality via the xref:configuration-guide:v2-api.adoc[v2 API].
24+
See xref:indexing-with-v2-apis.adoc[] for details on the v2 update endpoints and their differences from the v1 handlers described on this page.
25+
2326
The recommended way to configure and use request handlers is with path based names that map to paths in the request URL.
2427
However, request handlers can also be specified with the `qt` (query type) parameter if the xref:configuration-guide:requestdispatcher.adoc[`requestDispatcher`] is appropriately configured.
2528
It is possible to access the same handler using more than one name, which can be useful if you wish to specify different sets of default options.

‎solr/solr-ref-guide/modules/indexing-guide/pages/indexing-with-v2-apis.adoc‎

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
= Indexing with the V2 Update API
2+
// Licensed to the Apache Software Foundation (ASF) under one
3+
// or more contributor license agreements. See the NOTICE file
4+
// distributed with this work for additional information
5+
// regarding copyright ownership. The ASF licenses this file
6+
// to you under the Apache License, Version 2.0 (the
7+
// "License"); you may not use this file except in compliance
8+
// with the License. You may obtain a copy of the License at
9+
//
10+
// http://www.apache.org/licenses/LICENSE-2.0
11+
//
12+
// Unless required by applicable law or agreed to in writing,
13+
// software distributed under the License is distributed on an
14+
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15+
// KIND, either express or implied. See the License for the
16+
// specific language governing permissions and limitations
17+
// under the License.
18+
19+
Solr's xref:configuration-guide:v2-api.adoc[v2 API] provides update endpoints under the `/api` path prefix.
20+
These endpoints accept the same document formats as the xref:indexing-with-update-handlers.adoc[v1 update handlers], with some important differences described below.
21+
22+
NOTE: The v2 API is classified as "experimental" and may change in backwards-incompatible ways.
23+
24+
== V2 Update Endpoint Paths
25+
26+
For a SolrCloud collection the v2 update base path is:
27+
28+
----
29+
/api/collections/{collection}/update
30+
----
31+
32+
For a standalone core the v2 update base path is:
33+
34+
----
35+
/api/cores/{core}/update
36+
----
37+
38+
The following sub-paths are available:
39+
40+
[width="100%",options="header",]
41+
|===
42+
|Path |Accepted Format |Notes
43+
|`/update` |JSON (array of documents) |Equivalent to v1 `/update/json/docs`; document arrays only
44+
|`/update/json` |JSON (array of documents) |Same behavior as `/update`; document arrays only
45+
|`/update/xml` |XML |Supports full XML update syntax (add, delete, commit, optimize)
46+
|`/update/csv` |CSV |Equivalent to v1 `/update/csv`
47+
|`/update/bin` |JavaBin |Equivalent to v1 `/update` with `Content-Type: application/javabin`
48+
|===
49+
50+
IMPORTANT: The v2 `/update` and `/update/json` endpoints are document-only: they process a JSON array of documents (like the v1 `/update/json/docs` path) and do *not* support the full xref:indexing-with-update-handlers.adoc#sending-json-update-commands[JSON update command syntax] (commit, delete, optimize within the request body).
51+
Use `/update/xml` for those operations, or issue commit/rollback via separate API calls.
52+
53+
== JSON Document Indexing
54+
55+
The v2 `/update` and `/update/json` endpoints both accept a JSON array of documents:
56+
57+
[source,bash]
58+
----
59+
curl -X POST -H 'Content-Type: application/json' \
60+
'http://localhost:8983/api/collections/my_collection/update?commit=true' \
61+
--data-binary '
62+
[
63+
{
64+
"id": "1",
65+
"title": "Doc 1"
66+
},
67+
{
68+
"id": "2",
69+
"title": "Doc 2"
70+
}
71+
]'
72+
----
73+
74+
A single document can also be posted as a JSON object:
75+
76+
[source,bash]
77+
----
78+
curl -X POST -H 'Content-Type: application/json' \
79+
'http://localhost:8983/api/collections/my_collection/update?commit=true' \
80+
--data-binary '
81+
{
82+
"id": "1",
83+
"title": "Doc 1"
84+
}'
85+
----
86+
87+
Query parameters such as `commit`, `commitWithin`, and `overwrite` can be appended to the URL, as shown above.
88+
89+
== XML Document Indexing
90+
91+
The v2 `/update/xml` endpoint accepts the same XML format as the v1 `/update` handler and supports the full XML update syntax, including add, delete, commit, and optimize commands.
92+
93+
[source,bash]
94+
----
95+
curl -X POST -H 'Content-Type: application/xml' \
96+
'http://localhost:8983/api/collections/my_collection/update/xml' \
97+
--data-binary '
98+
<add>
99+
<doc>
100+
<field name="id">1</field>
101+
<field name="title">Doc 1</field>
102+
</doc>
103+
</add>'
104+
----
105+
106+
Delete by ID and delete by query are also supported:
107+
108+
[source,bash]
109+
----
110+
curl -X POST -H 'Content-Type: application/xml' \
111+
'http://localhost:8983/api/collections/my_collection/update/xml?commit=true' \
112+
--data-binary '
113+
<delete>
114+
<id>1</id>
115+
<query>title:unwanted</query>
116+
</delete>'
117+
----
118+
119+
== CSV Document Indexing
120+
121+
The v2 `/update/csv` endpoint accepts CSV-formatted documents and supports the same xref:indexing-with-update-handlers.adoc#csv-update-parameters[CSV update parameters] as the v1 handler:
122+
123+
[source,bash]
124+
----
125+
curl -X POST -H 'Content-Type: text/csv' \
126+
'http://localhost:8983/api/collections/my_collection/update/csv?commit=true' \
127+
--data-binary '
128+
id,title
129+
1,Doc 1
130+
2,Doc 2'
131+
----
132+
133+
== JavaBin Document Indexing
134+
135+
The v2 `/update/bin` endpoint accepts documents in JavaBin format, which is the native binary format used by SolrJ.
136+
This endpoint is primarily intended for use by SolrJ clients.
137+
138+
== Commit and Rollback
139+
140+
Because the v2 `/update` and `/update/json` endpoints do not support update commands in the request body, commits and rollbacks must be issued separately.
141+
Use the `commit=true` or `commitWithin=N` URL parameters to commit after indexing:
142+
143+
[source,bash]
144+
----
145+
curl -X POST -H 'Content-Type: application/json' \
146+
'http://localhost:8983/api/collections/my_collection/update?commit=true' \
147+
--data-binary '[{"id":"1","title":"Doc 1"}]'
148+
----
149+
150+
For a soft commit:
151+
152+
[source,bash]
153+
----
154+
curl -X POST -H 'Content-Type: application/json' \
155+
'http://localhost:8983/api/collections/my_collection/update?softCommit=true' \
156+
--data-binary '[{"id":"1","title":"Doc 1"}]'
157+
----
158+
159+
Alternatively, use `/update/xml` to issue an explicit commit command:
160+
161+
[source,bash]
162+
----
163+
curl -X POST -H 'Content-Type: application/xml' \
164+
'http://localhost:8983/api/collections/my_collection/update/xml' \
165+
--data-binary '<commit/>'
166+
----
167+
168+
== Comparison with V1 Update Handlers
169+
170+
The table below summarizes the key differences between the v1 and v2 update endpoints.
171+
172+
[width="100%",options="header",]
173+
|===
174+
|Feature |V1 |V2
175+
|Base path |`/solr/{collection}/update` |`/api/collections/{collection}/update`
176+
|JSON documents |`/update` or `/update/json/docs` |`/update` or `/update/json`
177+
|JSON update commands (commit/delete/optimize) |`/update` |Not supported via `/update` or `/update/json`; use `/update/xml` or URL params
178+
|XML updates |`/update` (via Content-Type) |`/update/xml`
179+
|CSV updates |`/update/csv` |`/update/csv`
180+
|JavaBin updates |`/update` (via Content-Type) |`/update/bin`
181+
|===
182+
183+
For full details on the v1 update handlers, see xref:indexing-with-update-handlers.adoc[].

0 commit comments

Comments
 (0)