You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucene.apache.org by ho...@apache.org on 2020/07/31 18:43:26 UTC
[lucene-solr] 02/02: SOLR-14383: tweaks bassed on feedback from
smiley
This is an automated email from the ASF dual-hosted git repository.
hossman pushed a commit to branch jira/SOLR-14383
in repository https://gitbox.apache.org/repos/asf/lucene-solr.git
commit 7086d6765215c1137ccc623468d4925a595d1fea
Author: Chris Hostetter <ho...@apache.org>
AuthorDate: Fri Jul 31 11:14:58 2020 -0700
SOLR-14383: tweaks bassed on feedback from smiley
- typo fixes
- using TIP box to draw attention to prefix routing
- switch from 'producs+skus+docs' to 'products+skus+manuals' for examples
---
.../src/indexing-nested-documents.adoc | 60 ++++++++++++----------
.../src/searching-nested-documents.adoc | 20 ++++----
.../src/transforming-result-documents.adoc | 8 +--
.../src/updating-parts-of-documents.adoc | 26 +++++-----
4 files changed, 59 insertions(+), 55 deletions(-)
diff --git a/solr/solr-ref-guide/src/indexing-nested-documents.adoc b/solr/solr-ref-guide/src/indexing-nested-documents.adoc
index 7b53600..85c6943 100644
--- a/solr/solr-ref-guide/src/indexing-nested-documents.adoc
+++ b/solr/solr-ref-guide/src/indexing-nested-documents.adoc
@@ -36,11 +36,11 @@ With the exception of in-place updates, <<#maintaining-integrity-with-updates-an
[#example-indexing-syntax]
== Example Indexing Syntax: Psuedo-Fields
-This example shows what it looks like to index two root level "product" documents, each containing two different types of child documents specified in "psuedo-fields": "skus" and "docs". Two of the "sku" type documents have their own nested child "docs" documents...
+This example shows what it looks like to index two root level "product" documents, each containing two different types of child documents specified in "psuedo-fields": "skus" and "manuals". Two of the "sku" type documents have their own nested child "manuals" documents...
[NOTE]
====
-Even though the child documents in these examples are provided syntactically as field values syntactically, this is simply a matter of syntax and as such `skus` and `docs` are not actual fields in the documents. Consequently, these field names need not be defined in the schema and probably shouldn't be as it would be confusing. There is no "child document" field type.
+Even though the child documents in these examples are provided syntactically as field values syntactically, this is simply a matter of syntax and as such `skus` and `manuals` are not actual fields in the documents. Consequently, these field names need not be defined in the schema and probably shouldn't be as it would be confusing. There is no "child document" field type.
====
//
@@ -61,23 +61,23 @@ Even though the child documents in these examples are provided syntactically as
"skus": [ { "id": "P11!S21",
"color_s": "RED",
"price_i": 42,
- "docs": [ { "id": "P11!D41",
- "name_s": "Red Swingline Brochure",
- "content_t": "..."
- } ]
+ "manuals": [ { "id": "P11!D41",
+ "name_s": "Red Swingline Brochure",
+ "content_t": "..."
+ } ]
},
{ "id": "P11!S31",
"color_s": "BLACK",
"price_i": 3
} ],
- "docs": [ { "id": "P11!D51",
- "name_s": "Quick Reference Guide",
- "content_t": "How to use your stapler ..."
- },
- { "id": "P11!D61",
- "name_s": "Warranty Details",
- "content_t": "... lifetime garuntee ..."
- } ]
+ "manuals": [ { "id": "P11!D51",
+ "name_s": "Quick Reference Guide",
+ "content_t": "How to use your stapler ..."
+ },
+ { "id": "P11!D61",
+ "name_s": "Warranty Details",
+ "content_t": "... lifetime guarantee ..."
+ } ]
},
{ "id": "P22!prod",
"name_s": "Mont Blanc Fountain Pen",
@@ -85,19 +85,19 @@ Even though the child documents in these examples are provided syntactically as
"skus": [ { "id": "P22!S22",
"color_s": "RED",
"price_i": 89,
- "docs": [ { "id": "P21!D41",
- "name_s": "Red Mont Blanc Brochure",
- "content_t": "..."
- } ]
+ "manuals": [ { "id": "P21!D41",
+ "name_s": "Red Mont Blanc Brochure",
+ "content_t": "..."
+ } ]
},
{ "id": "P22!S32",
"color_s": "BLACK",
"price_i": 67
} ],
- "docs": [ { "id": "P22!D52",
- "name_s": "How To Use A Pen",
- "content_t": "Start by removing the cap ..."
- } ]
+ "manuals": [ { "id": "P22!D52",
+ "name_s": "How To Use A Pen",
+ "content_t": "Start by removing the cap ..."
+ } ]
} ]
----
// end::sample-indexing-deeply-nested-documents[]
@@ -148,7 +148,6 @@ There are several additional schema considerations that should be considered for
** All field names in the schema can only be configured in one -- different types of child documents can not have the same field name configured in different ways.
** It may be infeasible to use `required` for any field names that aren't reqiured for all types of documents.
** Even child documents need a _globally_ unique `id`.
-*** When using Solr Cloud it is a _VERY_ good idea to use <<shards-and-indexing-data-in-solrcloud#document-routing,prefix based compositeIds>> with a common prefix for all documents in the block. This makes it much easier to apply <<updating-parts-of-documents#updating-child-documents,atomic updates to individual child documents>>
* `\_root_` must be configured to either be stored (`stored="true"`) or use doc values (`docValues="true"`) to enable <<updating-parts-of-documents#updating-child-documents,atomic updates of nested documents>>.
** Also, beware of `uniqueBlock(\_root_)` <<json-facet-api#stat-facet-functions,field type limitation>>, if you plan to use one.
* `\_nest_path_` is an optional field that (if definied) will be populated by Solr automatically with the ancestor path of each non-root document.
@@ -160,8 +159,8 @@ There are several additional schema considerations that should be considered for
----
** This field is neccessary if you wish to use <<updating-parts-of-documents#updating-child-documents,atomic updates of nested documents>>
** This field is neccessary in order for Solr to properly record & reconstruct the nested relationship of documents when using the `<<searching-nested-documents.adoc#child-doc-transformer,[child]>>` doc transformer.
-*** If this field does not exist, the `[child]` transformer will return all descendent child docs as a flattened list -- just as if they had been <<#indexing-anonymous-children,indexed as anonymous children>>.
-** If you do not use `\_nest_path_` it is strongly recomended that every document have some field that differentiates root docs from their nested children -- and differentiates different "types" of child documents. This is not strictly neccessary, so long as it's possible to write a "filter" query that can be used to isolate and select only parent documents for use in the <<other-parsers.adoc#block-join-query-parsers,block join query parsers>> and <<searching-nested-documents.adoc#child [...]
+*** If this field does not exist, the `[child]` transformer will return all descendent child documents as a flattened list -- just as if they had been <<#indexing-anonymous-children,indexed as anonymous children>>.
+** If you do not use `\_nest_path_` it is strongly recomended that every document have some field that differentiates root documents from their nested children -- and differentiates different "types" of child documents. This is not strictly neccessary, so long as it's possible to write a "filter" query that can be used to isolate and select only parent documents for use in the <<other-parsers.adoc#block-join-query-parsers,block join query parsers>> and <<searching-nested-documents.adoc# [...]
* `\_nest_parent_` is an optional field that (if defined) will be populated by Solr automatically to store the `id` of each document's _immediate_ parent document (if there is one).
+
[sourece,xml]
@@ -169,6 +168,11 @@ There are several additional schema considerations that should be considered for
<field name="_nest_parent_" type="string" indexed="true" stored="true" />
----
+[TIP]
+====
+When using Solr Cloud it is a _VERY_ good idea to use <<shards-and-indexing-data-in-solrcloud#document-routing,prefix based compositeIds>> with a common prefix for all documents in the block. This makes it much easier to apply <<updating-parts-of-documents#updating-child-documents,atomic updates to individual child documents>>
+====
+
== Maintaining Integrity with Updates and Deletes
@@ -223,7 +227,7 @@ Although not recommended, it is also possible to index child documents "anonymou
{ "id": "P11!D61",
"type_s": "DOC",
"name_s": "Warranty Details",
- "content_t": "... lifetime garuntee ..."
+ "content_t": "... lifetime guarantee ..."
}
]
} ]
@@ -304,7 +308,7 @@ $ curl --globoff 'http://localhost:8983/solr/gettingstarted/select?omitHeader=tr
"id":"P11!D61",
"type_s":"DOC",
"name_s":"Warranty Details",
- "content_t":"... lifetime garuntee ...",
+ "content_t":"... lifetime guarantee ...",
"_version_":1673055562829398016}]}]
}}
----
@@ -354,7 +358,7 @@ $ curl --globoff 'http://localhost:8983/solr/gettingstarted/select?omitHeader=tr
<str name="id">P11!D61</str>
<str name="type_s">DOC</str>
<str name="name_s">Warranty Details</str>
- <str name="content_t">... lifetime garuntee ...</str>
+ <str name="content_t">... lifetime guarantee ...</str>
<long name="_version_">1673055562829398016</long></doc></doc>
</result>
</response>
diff --git a/solr/solr-ref-guide/src/searching-nested-documents.adoc b/solr/solr-ref-guide/src/searching-nested-documents.adoc
index 29ea585..057d6d4 100644
--- a/solr/solr-ref-guide/src/searching-nested-documents.adoc
+++ b/solr/solr-ref-guide/src/searching-nested-documents.adoc
@@ -35,7 +35,7 @@ include::indexing-nested-documents.adoc[tag=sample-indexing-deeply-nested-docume
=== Child Doc Transformer
-By default, documents that match a query do not include any of thir nested children in the response. The `[child]` Doc Transformer Can be used enrich query results with the documents' descendants.
+By default, documents that match a query do not include any of their nested children in the response. The `[child]` Doc Transformer Can be used enrich query results with the documents' descendants.
For a detailed explanation of this transformer, and specifics on it's syntax & limitations, please refer to the section <<transforming-result-documents.adoc#child-childdoctransformerfactory, [child] - ChildDocTransformerFactory>>.
@@ -72,7 +72,7 @@ $ curl 'http://localhost:8983/solr/gettingstarted/select?omitHeader=true&q=descr
"color_s":"RED",
"price_i":42,
"_version_":1672933224035123200,
- "docs":[
+ "manuals":[
{
"id":"P11!D41",
"name_s":"Red Swingline Brochure",
@@ -84,7 +84,7 @@ $ curl 'http://localhost:8983/solr/gettingstarted/select?omitHeader=true&q=descr
"color_s":"BLACK",
"price_i":3,
"_version_":1672933224035123200}],
- "docs":[
+ "manuals":[
{
"id":"P11!D51",
"name_s":"Quick Reference Guide",
@@ -94,7 +94,7 @@ $ curl 'http://localhost:8983/solr/gettingstarted/select?omitHeader=true&q=descr
{
"id":"P11!D61",
"name_s":"Warranty Details",
- "content_t":"... lifetime garuntee ...",
+ "content_t":"... lifetime guarantee ...",
"_version_":1672933224035123200}]}]
}}
----
@@ -134,7 +134,7 @@ $ curl --globoff 'http://localhost:8983/solr/gettingstarted/select?omitHeader=tr
{
"id":"P11!D61",
"name_s":"Warranty Details",
- "content_t":"... lifetime garuntee ...",
+ "content_t":"... lifetime guarantee ...",
"_version_":1672933224035123200}]
}}
----
@@ -198,13 +198,13 @@ Here for example is a query where:
* the (sku) documents returned must have a color of "RED"
* the (sku) docments returned must be the descendents of root level (product) documents which have:
-** immediate child "docs" documents which have:
-*** "lifetime garuntee" in their content
-* each return (sku) document also includes any descendent (docs) documents it has
+** immediate child "manuals" documents which have:
+*** "lifetime guarantee" in their content
+* each return (sku) document also includes any descendent (manuals) documents it has
[source,bash]
----
-$ curl --globoff 'http://localhost:8983/solr/gettingstarted/select?omitHeader=true&fq=color_s:RED&q={!child+of="*:*+-_nest_path_:*"+filters=$parent_fq}&parent_fq={!parent+which="*:*+-_nest_path_:*"}_nest_path_:"/docs"+AND+content_t:"lifetime+garuntee"&fl=*,[child]'
+$ curl --globoff 'http://localhost:8983/solr/gettingstarted/select?omitHeader=true&fq=color_s:RED&q={!child+of="*:*+-_nest_path_:*"+filters=$parent_fq}&parent_fq={!parent+which="*:*+-_nest_path_:*"}_nest_path_:"/manuals"+AND+content_t:"lifetime+guarantee"&fl=*,[child]'
{
"response":{"numFound":1,"start":0,"maxScore":1.4E-45,"numFoundExact":true,"docs":[
{
@@ -212,7 +212,7 @@ $ curl --globoff 'http://localhost:8983/solr/gettingstarted/select?omitHeader=tr
"color_s":"RED",
"price_i":42,
"_version_":1672933224035123200,
- "docs":[
+ "manuals":[
{
"id":"P11!D41",
"name_s":"Red Swingline Brochure",
diff --git a/solr/solr-ref-guide/src/transforming-result-documents.adoc b/solr/solr-ref-guide/src/transforming-result-documents.adoc
index 95eaf9a..7394097 100644
--- a/solr/solr-ref-guide/src/transforming-result-documents.adoc
+++ b/solr/solr-ref-guide/src/transforming-result-documents.adoc
@@ -168,13 +168,13 @@ Some Examples:
** Matches any documents that are descendents of the current document and have a "nested path" of `/skus` -- but not any children of those `skus`
* childFilter="/skus/color_s:RED"
** Matches any documents that are descendents of the current document; match `color_s:RED`; and have a "nested path" of `/skus` -- but not any children of those `skus`
-* `childFilter="/skus/docs/\*:*"`
-** Matches any documents that are descendents of the current document and have a "nested path" of `/skus/docs` -- but not any children of those `docs`
+* `childFilter="/skus/manuals/\*:*"`
+** Matches any documents that are descendents of the current document and have a "nested path" of `/skus/manuals` -- but not any children of those `manuals`
When paths do not start with a `/` they are treated as "path suffixes":
-* `childFilter="docs/\*:*"`
-** Matches any documents that are descendents of the current document and have a "nested path" that ends with "docs", regardless of how deeply nested they are -- but not any children of those `docs`
+* `childFilter="manuals/\*:*"`
+** Matches any documents that are descendents of the current document and have a "nested path" that ends with "manuals", regardless of how deeply nested they are -- but not any children of those `manuals`
====
diff --git a/solr/solr-ref-guide/src/updating-parts-of-documents.adoc b/solr/solr-ref-guide/src/updating-parts-of-documents.adoc
index ecdc447..ccd09e4 100644
--- a/solr/solr-ref-guide/src/updating-parts-of-documents.adoc
+++ b/solr/solr-ref-guide/src/updating-parts-of-documents.adoc
@@ -156,14 +156,14 @@ As with normal (multiValued) fields, the `set` keyword can be used to replace al
curl -X POST 'http://localhost:8983/solr/gettingstarted/update?commit=true' -H 'Content-Type: application/json' --data-binary '[
{
"id": "P22!S22",
- "docs": { "set": [ { "id": "P22!D77",
- "name_s": "Why Red Pens Are the Best",
- "content_t": "... correcting papers ...",
- },
- { "id": "P22!D88",
- "name_s": "How to get Red ink stains out of fabric",
- "content_t": "... vinegar ...",
- } ] }
+ "manuals": { "set": [ { "id": "P22!D77",
+ "name_s": "Why Red Pens Are the Best",
+ "content_t": "... correcting papers ...",
+ },
+ { "id": "P22!D88",
+ "name_s": "How to get Red ink stains out of fabric",
+ "content_t": "... vinegar ...",
+ } ] }
} ]'
----
@@ -177,10 +177,10 @@ As with normal (multiValued) fields, the `add` keyword can be used to add additi
curl -X POST 'http://localhost:8983/solr/gettingstarted/update?commit=true' -H 'Content-Type: application/json' --data-binary '[
{
"id": "P11!S21",
- "docs": { "add": { "id": "P11!D99",
- "name_s": "Why Red Staplers Are the Best",
- "content_t": "Once upon a time, Mike Judge ...",
- } }
+ "manuals": { "add": { "id": "P11!D99",
+ "name_s": "Why Red Staplers Are the Best",
+ "content_t": "Once upon a time, Mike Judge ...",
+ } }
} ]'
----
@@ -194,7 +194,7 @@ As with normal (multiValued) fields, the `remove` keyword can be used to remove
curl -X POST 'http://localhost:8983/solr/gettingstarted/update?commit=true' -H 'Content-Type: application/json' --data-binary '[
{
"id": "P11!S21",
- "docs": { "remove": { "id": "P11!D41" } }
+ "manuals": { "remove": { "id": "P11!D41" } }
} ]'
----