You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@solr.apache.org by GitBox <gi...@apache.org> on 2021/12/23 17:57:07 UTC

[GitHub] [solr] alessandrobenedetti opened a new pull request #476: SOLR-14397

alessandrobenedetti opened a new pull request #476:
URL: https://github.com/apache/solr/pull/476


   https://issues.apache.org/jira/browse/SOLR-14397
   
   
   
   # Description
   
   This is the first milestone in integrating neural search in Apache Solr.
   It includes a DenseVectorField to wrap the Lucene implementation using Hierarchical Navigable Small World to index the dense vector.
   It includes a Knn query parser to run K Nearest Neighbors query.
   
   # Solution
   
   A new Apache Solr field Type has been added.
   A new Apache Solr Query Parser has been added.
   
   # Tests
   
   Dense vector fields and the query parser have tests.
   
   # Checklist
   
   Please review the following and check all that apply:
   
   - [X] I have reviewed the guidelines for [How to Contribute](https://wiki.apache.org/solr/HowToContribute) and my code conforms to the standards described there to the best of my ability.
   - [X] I have created a Jira issue and added the issue ID to my pull request title.
   - [X] I have given Solr maintainers [access](https://help.github.com/en/articles/allowing-changes-to-a-pull-request-branch-created-from-a-fork) to contribute to my PR branch. (optional but recommended)
   - [X] I have developed this patch against the `main` branch.
   - [ ] I have run `./gradlew check`.
   - [X] I have added tests for my changes.
   - [ ] I have added documentation for the [Reference Guide](https://github.com/apache/solr/tree/main/solr/solr-ref-guide)
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r776772098



##########
File path: solr/core/src/java/org/apache/solr/schema/DenseVectorField.java
##########
@@ -0,0 +1,200 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.solr.schema;
+
+import org.apache.lucene.document.KnnVectorField;
+import org.apache.lucene.document.StoredField;
+import org.apache.lucene.index.IndexableField;
+import org.apache.lucene.index.VectorSimilarityFunction;
+import org.apache.lucene.queries.function.ValueSource;
+import org.apache.lucene.search.KnnVectorQuery;
+import org.apache.lucene.search.Query;
+import org.apache.lucene.search.SortField;
+import org.apache.solr.common.SolrException;
+import org.apache.solr.response.TextResponseWriter;
+import org.apache.solr.search.QParser;
+import org.apache.solr.uninverting.UninvertingReader;
+
+import java.io.IOException;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
+
+import static java.util.Optional.ofNullable;
+
+/**
+ * Provides a field type to support Lucene's {@link
+ * org.apache.lucene.document.KnnVectorField}.
+ * See {@link org.apache.lucene.search.KnnVectorQuery} for more details.
+ * It supports a fixed cardinality dimension for the vector and a fixed similarity function.
+ * The default similarity is EUCLIDEAN_HNSW (L2).

Review comment:
       All supported similarities are detailed in the .adoc detailed page in the pull request.
   In my opinion here the link to the Lucene class suffices.
   But I am open to suggestion!




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r783023194



##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,320 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+With the *Neural Search* module Apache Solr is introducing support for neural networks based techniques that can improve various aspects of search.

Review comment:
       I am not a native speaker, but is "With the *Neural Search* module Apache Solr is support for neural networks based techniques" correct? I didn't know of the construct:
   "with '<something>' Apache Solr is support for '<something>'
   




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880: K Nearest Neighbors Search

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r787667272



##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not be solved simply by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+
+=== DenseVectorField
+The Dense Vector field gives the possibility of indexing and searching dense vectors of float elements.
+
+e.g.
+
+`[1.0, 2.5, 3.7, 4.1]` (array of float elements)
+
+Here's how `DenseVectorField` should be configured in the schema:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`vectorDimension`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The dimension of the dense vector to pass in.
++
+Accepted values:
+Integer < = 1024.
+
+`similarityFunction`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `euclidean`
+|===
++
+Vector similarity function; used in search to return top K most similar vectors to a target vector.
++
+Accepted values: `euclidean`, `dot_product`  or `cosine`.
+
+* `euclidean`: https://en.wikipedia.org/wiki/Euclidean_distance[Euclidean distance]
+* `dot_product`: https://en.wikipedia.org/wiki/Dot_product[Dot product]. *NOTE*: this similarity is intended as an optimized way to perform cosine similarity. In order to use it, all vectors must be of unit length, including both document and query vectors. Using dot product with vectors that are not unit length can result in errors or poor search results..
+* `cosine`: https://en.wikipedia.org/wiki/Cosine_similarity[Cosine similarity]. *NOTE*: the preferred way to perform cosine similarity is to normalize all vectors to unit length, and instead use DOT_PRODUCT. You should only use this function if you need to preserve the original vectors and cannot normalize them in advance.
+
+*N.B.* To use the following advanced parameters that customise the codec format
+and the hyper-parameter of the HNSW algorithm make sure you set this configuration in the solrconfig.xml:
+[source,xml]
+<config>
+<codecFactory class="solr.SchemaCodecFactory"/>
+...
+
+Here's how `DenseVectorField` can be configured with the advanced codec hyper-parameters:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine" codecFormat="Lucene90HnswVectorsFormat" hnswMaxConnections="10" hnswBeamWidth="40"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`codecFormat`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `Lucene90HnswVectorsFormat`
+|===
++
+(advanced) Specifies the knn codec implementation to use
++
+
+Accepted values: `Lucene90HnswVectorsFormat`.
+
+Please note that the `codecFormat` accepted values may change in future releases.
+
+
+
+[NOTE]
+Lucene index back-compatibility is only supported for the default codec.
+If you choose to customize the `codecFormat` in your schema, upgrading to a future version of Solr may require you to either switch back to the default codec and optimize your index to rewrite it into the default codec before upgrading, or re-build your entire index from scratch after upgrading.
+
+`hnswMaxConnections`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 16
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+Controls how many of the nearest neighbor candidates are connected to the new node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `M` from the later paper.
++
+Accepted values:
+Integer.
+
+`hnswBeamWidth`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 100
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+It is the number of nearest neighbor candidates to track while searching the graph for each newly inserted node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `efConstruction` from the later paper.
++
+Accepted values:
+Integer.
+
+DenseVectorField supports the attributes: `indexed`, `stored`.
+
+*N.B.* currently multivalue is not supported
+
+Here's how a `DenseVectorField` should be indexed:
+
+[.dynamic-tabs]
+--
+[example.tab-pane#json]
+====
+[.tab-label]*JSON*
+[source,json]
+----
+[{ "id": "1",
+"vector": [1.0, 2.5, 3.7, 4.1]
+},
+{ "id": "2",
+"vector": [1.5, 5.5, 6.7, 65.1]
+}
+]
+----
+====
+
+[example.tab-pane#xml]
+====
+[.tab-label]*XML*
+[source,xml]
+----
+<add>
+<doc>
+<field name="id">1</field>
+<field name="vector">1.0</field>
+<field name="vector">2.5</field>
+<field name="vector">3.7</field>
+<field name="vector">4.1</field>
+</doc>
+<doc>
+<field name="id">2</field>
+<field name="vector">1.5</field>
+<field name="vector">5.5</field>
+<field name="vector">6.7</field>
+<field name="vector">65.1</field>
+</doc>
+</add>
+----
+====
+
+[example.tab-pane#solrj]
+====
+[.tab-label]*SolrJ*
+[source,java,indent=0]
+----
+final SolrClient client = getSolrClient();
+
+final SolrInputDocument d1 = new SolrInputDocument();
+d1.setField("id", "1");
+d1.setField("vector", Arrays.asList(1.0f, 2.5f, 3.7f, 4.1f));
+
+
+final SolrInputDocument d2 = new SolrInputDocument();
+d2.setField("id", "2");
+d2.setField("vector", Arrays.asList(1.5f, 5.5f, 6.7f, 65.1f));
+
+client.add(Arrays.asList(d1, d2));
+----
+====
+--
+
+== Query Time
+This is the list of Apache Solr query approaches designed to support Neural Search:
+
+=== knn Query Parser
+The `knn` K-Nearest Neighbors query parser allows to find the k-nearest documents to the target vector according to indexed dense vectors in the given field.
+
+The score for a retrieved document is the approximate distance to the target vector(defined by the similarityFunction configured at indexing time).
+
+It takes the following parameters:
+
+`f`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The DenseVectorField to search in.
+
+`topK`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 10
+|===
++
+How many k-nearest results to return.
+
+Here's how to run a KNN search:
+
+[source,text]
+&q={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]
+
+The search results retrieved are the K-nearest to the vector in input `[1.0, 2.0, 3.0, 4.0]`, ranked by the similarityFunction configured at indexing time.
+
+==== Usage with Filter Queries
+The `knn` query parser can be used in filter queries:
+[source,text]
+&q=id:(1 2 3)&fq={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]
+
+The `knn` query parser can be used with filter queries:
+[source,text]
+&q={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]&fq=id:(1 2 3)
+
+[IMPORTANT]
+====
+When using `knn` in these scenarios make sure you have a clear understanding of how filter queries work in Apache Solr:
+
+The Ranked List of document IDs resulting from the main query `q` is intersected with the set of document IDs deriving from each filter query `fq`.
+
+e.g.
+
+Ranked List from `q`=`[ID1, ID4, ID2, ID10]` <intersects> Set from `fq`=`{ID3, ID2, ID9, ID4}` = `[ID4,ID2]`
+====
+
+
+==== Usage as Re-Ranking Query
+The `knn` query parser can be used to rerank first pass query results:
+[source,text]
+&q=id:(3 4 9 2)&rq={!rerank reRankQuery=$rqq reRankDocs=4 reRankWeight=1}&rqq={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]
+
+[IMPORTANT]
+====
+When using `knn` in reranking pay attention to the `topK` parameter.
+
+The second pass score(deriving from knn) is calculated only if the document `d` from the first pass is within
+the K-nearest neighbors(*in the whole index*) of the target vector to search.
+
+This means the second pass `knn` is executed on the whole index anyway, which is a current limitation.
+
+The final ranked list of results will have the first pass score(main query `q`) added to the second pass score(the approximated similarityFunction distance to the target vector to search) multiplied by a multiplicative factor(reRankWeight).
+
+Details about using the ReRank Query Parser can be found in the <<query-re-ranking.adoc#,Query Re-Ranking>> section.
+====
+
+== Additional Neural Search Resources

Review comment:
       Just edited to "Additional Resources".
   
   I took inspiration from the https://solr.apache.org/guide/6_6/learning-to-rank.html#learning-to-rank
   
   I think it's fine to start with a couple of blog posts(I'll publish them when merging the contrib).
   This list is supposed to grow with additional links from the community later.
   
   I prefer to keep it at the end, because it feels cleaner, but if you think it's a blocker I can add it as a sentence




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880: K Nearest Neighbors Search

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r787632838



##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not be solved simply by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+

Review comment:
       Thanks for the correction!




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r786754601



##########
File path: solr/core/src/java/org/apache/solr/update/DocumentBuilder.java
##########
@@ -151,63 +153,49 @@ public static Document toDocument(SolrInputDocument doc, IndexSchema schema, boo
 
       String name = field.getName();
       SchemaField sfield = schema.getFieldOrNull(name);
-      boolean used = false;
       
+      List<CopyField> copyFields = schema.getCopyFieldsList(name);
+      if( copyFields.size() == 0 ) copyFields = null;
+
       // Make sure it has the correct number
-      if( sfield!=null && !sfield.multiValued() && field.getValueCount() > 1 ) {
+      if( sfield!=null && !(sfield.getType() instanceof DenseVectorField) && !sfield.multiValued() && field.getValueCount() > 1 ) {
         throw new SolrException( SolrException.ErrorCode.BAD_REQUEST,
-            "ERROR: "+getID(doc, schema)+"multiple values encountered for non multiValued field " + 
-              sfield.getName() + ": " +field.getValue() );
+                "ERROR: "+getID(doc, schema)+"multiple values encountered for non multiValued field " +
+                        sfield.getName() + ": " +field.getValue() );
       }
 
-      List<CopyField> copyFields = schema.getCopyFieldsList(name);
-      if( copyFields.size() == 0 ) copyFields = null;
-

Review comment:
       makes sense! Done!




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880: K Nearest Neighbors Search

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r787660658



##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not be solved simply by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+
+=== DenseVectorField
+The Dense Vector field gives the possibility of indexing and searching dense vectors of float elements.
+
+e.g.
+
+`[1.0, 2.5, 3.7, 4.1]` (array of float elements)
+
+Here's how `DenseVectorField` should be configured in the schema:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`vectorDimension`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The dimension of the dense vector to pass in.
++
+Accepted values:
+Integer < = 1024.
+
+`similarityFunction`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `euclidean`
+|===
++
+Vector similarity function; used in search to return top K most similar vectors to a target vector.
++
+Accepted values: `euclidean`, `dot_product`  or `cosine`.
+
+* `euclidean`: https://en.wikipedia.org/wiki/Euclidean_distance[Euclidean distance]
+* `dot_product`: https://en.wikipedia.org/wiki/Dot_product[Dot product]. *NOTE*: this similarity is intended as an optimized way to perform cosine similarity. In order to use it, all vectors must be of unit length, including both document and query vectors. Using dot product with vectors that are not unit length can result in errors or poor search results..
+* `cosine`: https://en.wikipedia.org/wiki/Cosine_similarity[Cosine similarity]. *NOTE*: the preferred way to perform cosine similarity is to normalize all vectors to unit length, and instead use DOT_PRODUCT. You should only use this function if you need to preserve the original vectors and cannot normalize them in advance.
+
+*N.B.* To use the following advanced parameters that customise the codec format
+and the hyper-parameter of the HNSW algorithm make sure you set this configuration in the solrconfig.xml:
+[source,xml]
+<config>
+<codecFactory class="solr.SchemaCodecFactory"/>
+...
+
+Here's how `DenseVectorField` can be configured with the advanced codec hyper-parameters:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine" codecFormat="Lucene90HnswVectorsFormat" hnswMaxConnections="10" hnswBeamWidth="40"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`codecFormat`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `Lucene90HnswVectorsFormat`
+|===
++
+(advanced) Specifies the knn codec implementation to use
++
+
+Accepted values: `Lucene90HnswVectorsFormat`.
+
+Please note that the `codecFormat` accepted values may change in future releases.
+
+
+
+[NOTE]
+Lucene index back-compatibility is only supported for the default codec.
+If you choose to customize the `codecFormat` in your schema, upgrading to a future version of Solr may require you to either switch back to the default codec and optimize your index to rewrite it into the default codec before upgrading, or re-build your entire index from scratch after upgrading.
+
+`hnswMaxConnections`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 16
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+Controls how many of the nearest neighbor candidates are connected to the new node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `M` from the later paper.
++
+Accepted values:
+Integer.
+
+`hnswBeamWidth`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 100
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+It is the number of nearest neighbor candidates to track while searching the graph for each newly inserted node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `efConstruction` from the later paper.
++
+Accepted values:
+Integer.
+
+DenseVectorField supports the attributes: `indexed`, `stored`.
+
+*N.B.* currently multivalue is not supported
+
+Here's how a `DenseVectorField` should be indexed:
+
+[.dynamic-tabs]
+--
+[example.tab-pane#json]
+====
+[.tab-label]*JSON*
+[source,json]
+----
+[{ "id": "1",
+"vector": [1.0, 2.5, 3.7, 4.1]
+},
+{ "id": "2",
+"vector": [1.5, 5.5, 6.7, 65.1]
+}
+]
+----
+====
+
+[example.tab-pane#xml]
+====
+[.tab-label]*XML*
+[source,xml]
+----
+<add>
+<doc>
+<field name="id">1</field>
+<field name="vector">1.0</field>
+<field name="vector">2.5</field>
+<field name="vector">3.7</field>
+<field name="vector">4.1</field>
+</doc>
+<doc>
+<field name="id">2</field>
+<field name="vector">1.5</field>
+<field name="vector">5.5</field>
+<field name="vector">6.7</field>
+<field name="vector">65.1</field>
+</doc>
+</add>
+----
+====
+
+[example.tab-pane#solrj]
+====
+[.tab-label]*SolrJ*
+[source,java,indent=0]
+----
+final SolrClient client = getSolrClient();
+
+final SolrInputDocument d1 = new SolrInputDocument();
+d1.setField("id", "1");
+d1.setField("vector", Arrays.asList(1.0f, 2.5f, 3.7f, 4.1f));
+
+
+final SolrInputDocument d2 = new SolrInputDocument();
+d2.setField("id", "2");
+d2.setField("vector", Arrays.asList(1.5f, 5.5f, 6.7f, 65.1f));
+
+client.add(Arrays.asList(d1, d2));
+----
+====
+--
+
+== Query Time
+This is the list of Apache Solr query approaches designed to support Neural Search:
+
+=== knn Query Parser
+The `knn` K-Nearest Neighbors query parser allows to find the k-nearest documents to the target vector according to indexed dense vectors in the given field.
+
+The score for a retrieved document is the approximate distance to the target vector(defined by the similarityFunction configured at indexing time).
+
+It takes the following parameters:
+
+`f`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory

Review comment:
       Done!




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880: K Nearest Neighbors Search

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r787659388



##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not be solved simply by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+
+=== DenseVectorField
+The Dense Vector field gives the possibility of indexing and searching dense vectors of float elements.
+
+e.g.
+
+`[1.0, 2.5, 3.7, 4.1]` (array of float elements)
+
+Here's how `DenseVectorField` should be configured in the schema:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`vectorDimension`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The dimension of the dense vector to pass in.
++
+Accepted values:
+Integer < = 1024.
+
+`similarityFunction`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `euclidean`
+|===
++
+Vector similarity function; used in search to return top K most similar vectors to a target vector.
++
+Accepted values: `euclidean`, `dot_product`  or `cosine`.
+
+* `euclidean`: https://en.wikipedia.org/wiki/Euclidean_distance[Euclidean distance]
+* `dot_product`: https://en.wikipedia.org/wiki/Dot_product[Dot product]. *NOTE*: this similarity is intended as an optimized way to perform cosine similarity. In order to use it, all vectors must be of unit length, including both document and query vectors. Using dot product with vectors that are not unit length can result in errors or poor search results..
+* `cosine`: https://en.wikipedia.org/wiki/Cosine_similarity[Cosine similarity]. *NOTE*: the preferred way to perform cosine similarity is to normalize all vectors to unit length, and instead use DOT_PRODUCT. You should only use this function if you need to preserve the original vectors and cannot normalize them in advance.
+
+*N.B.* To use the following advanced parameters that customise the codec format
+and the hyper-parameter of the HNSW algorithm make sure you set this configuration in the solrconfig.xml:
+[source,xml]
+<config>
+<codecFactory class="solr.SchemaCodecFactory"/>
+...
+
+Here's how `DenseVectorField` can be configured with the advanced codec hyper-parameters:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine" codecFormat="Lucene90HnswVectorsFormat" hnswMaxConnections="10" hnswBeamWidth="40"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`codecFormat`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `Lucene90HnswVectorsFormat`
+|===
++
+(advanced) Specifies the knn codec implementation to use
++
+
+Accepted values: `Lucene90HnswVectorsFormat`.
+
+Please note that the `codecFormat` accepted values may change in future releases.
+
+
+
+[NOTE]
+Lucene index back-compatibility is only supported for the default codec.
+If you choose to customize the `codecFormat` in your schema, upgrading to a future version of Solr may require you to either switch back to the default codec and optimize your index to rewrite it into the default codec before upgrading, or re-build your entire index from scratch after upgrading.
+
+`hnswMaxConnections`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 16
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+Controls how many of the nearest neighbor candidates are connected to the new node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `M` from the later paper.
++
+Accepted values:
+Integer.
+
+`hnswBeamWidth`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 100
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+It is the number of nearest neighbor candidates to track while searching the graph for each newly inserted node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `efConstruction` from the later paper.
++
+Accepted values:
+Integer.
+
+DenseVectorField supports the attributes: `indexed`, `stored`.
+
+*N.B.* currently multivalue is not supported

Review comment:
       Thanks!




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r786789992



##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,322 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.

Review comment:
       great! Thanks @joel-bernstein and @cpoerschke !




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880: K Nearest Neighbors Search

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r789930090



##########
File path: solr/solr-ref-guide/src/dense-vector-search.adoc
##########
@@ -0,0 +1,308 @@
+= Dense Vector Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+The Apache Solr *Dense Vector Search* module adds support for indexing and searching dense numerical vectors.
+
+https://en.wikipedia.org/wiki/Deep_learning[Deep learning] can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+These neural network-based techniques are usually referred to as neural search, an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Important Concepts
+
+=== Dense Vector Representation 
+A dense vector describes information as an array of elements, each of them explicitly defined.

Review comment:
       That's brilliant! I just committed the changes!
   Resolving now!




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti merged pull request #476: SOLR-15880: K Nearest Neighbors Search

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti merged pull request #476:
URL: https://github.com/apache/solr/pull/476


   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] risdenk commented on a change in pull request #476: SOLR-15880

Posted by GitBox <gi...@apache.org>.
risdenk commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r782564735



##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,320 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+With the *Neural Search* module Apache Solr is introducing support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not simply be solved by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+
+=== DenseVectorField
+The Dense Vector field gives the possibility of indexing and searching dense vectors of float elements.
+
+e.g.
+
+`[1.0, 2.5, 3.7, 4.1]` (array of float elements)
+
+Here's how `DenseVectorField` should be configured in the schema:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`vectorDimension`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The dimension of the dense vector to pass in.
++
+Accepted values:
+Integer < = 1024.
+
+`similarityFunction`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `euclidean`
+|===
++
+Vector similarity function; used in search to return top K most similar vectors to a target vector.
++
+Accepted values: `euclidean`, `dot_product`  or `cosine`.
+
+* `euclidean`: https://en.wikipedia.org/wiki/Euclidean_distance[Euclidean distance]
+* `dot_product`: https://en.wikipedia.org/wiki/Dot_product[Dot product]. *NOTE*: this similarity is intended as an optimized way to perform cosine similarity. In order to use it, all vectors must be of unit length, including both document and query vectors. Using dot product with vectors that are not unit length can result in errors or poor search results..
+* `cosine`: https://en.wikipedia.org/wiki/Cosine_similarity[Cosine similarity]. *NOTE*: the preferred way to perform cosine similarity is to normalize all vectors to unit length, and instead use DOT_PRODUCT. You should only use this function if you need to preserve the original vectors and cannot normalize them in advance.
+
+*N.B.* To use the following advanced parameters that customise the codec format
+and the hyper-parameter of the HNSW algorithm make sure you set this configuration in the solrconfig.xml:
+[source,xml]
+<config>
+<codecFactory class="solr.SchemaCodecFactory"/>
+...
+
+Here's how `DenseVectorField` can be configured with the advanced codec hyper-parameters:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine" codecFormat="Lucene90HnswVectorsFormat" hnswMaxConnections="10" hnswBeamWidth="40"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`codecFormat`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `Lucene90HnswVectorsFormat`
+|===
++
+(advanced) Specifies the knn codec implementation to use
++
+
+Accepted values: `Lucene90HnswVectorsFormat`.
+
+Please note that the `codecFormat` accepted values may change in future releases.
+
+
+
+[NOTE]
+Lucene index back-compatibility is only supported for the default codec.
+If you choose to customize the `codecFormat` in your schema, upgrading to a future version of Solr may require you to either switch back to the default codec and optimize your index to rewrite it into the default codec before upgrading, or re-build your entire index from scratch after upgrading.
+
+`hnswMaxConnections`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 16
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+Controls how many of the nearest neighbor candidates are connected to the new node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `M` from the later paper.
++
+Accepted values:
+Integer.
+
+`hnswBeamWidth`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 100
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+It is the number of nearest neighbor candidates to track while searching the graph for each newly inserted node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `efConstruction` from the later paper.
++
+Accepted values:
+Integer.
+
+DenseVectorField supports the attributes: `indexed`, `stored`.
+
+*N.B.* currently multivalue is not supported
+
+Here's how a `DenseVectorField` should be indexed:
+
+[.dynamic-tabs]
+--
+[example.tab-pane#json]
+====
+[.tab-label]*JSON*
+[source,json]
+----
+[{ "id": "1",
+"vector": [1.0, 2.5, 3.7, 4.1]
+},
+{ "id": "2",
+"vector": [1.5, 5.5, 6.7, 65.1]
+}
+]
+----
+====
+
+[example.tab-pane#xml]
+====
+[.tab-label]*XML*
+[source,xml]
+----
+<add>
+<doc>
+<field name="id">1</field>
+<field name="vector">1.0</field>
+<field name="vector">2.5</field>
+<field name="vector">3.7</field>
+<field name="vector">4.1</field>
+</doc>
+<doc>
+<field name="id">2</field>
+<field name="vector">1.5</field>
+<field name="vector">5.5</field>
+<field name="vector">6.7</field>
+<field name="vector">65.1</field>
+</doc>
+</add>
+----
+====
+
+[example.tab-pane#solrj]
+====
+[.tab-label]*SolrJ*
+[source,java,indent=0]
+----
+final SolrClient client = getSolrClient();
+
+final SolrInputDocument d1 = new SolrInputDocument();
+d1.setField("id", "1");
+d1.setField("vector", Arrays.asList(1.0f, 2.5f, 3.7f, 4.1f));
+
+
+final SolrInputDocument d2 = new SolrInputDocument();
+d2.setField("id", "2");
+d2.setField("vector", Arrays.asList(1.5f, 5.5f, 6.7f, 65.1f));
+
+client.add(Arrays.asList(d1, d2));
+----
+====
+--
+
+== Query Time
+This is the list of Apache Solr query approaches designed to support Neural Search:
+
+=== knn Query Parser
+The `knn` K-Nearest Neighbors query parser allows to find the k-nearest documents to the target vector according to indexed dense vectors in the given field.
+
+It takes the following parameters:
+
+`f`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The DenseVectorField to search in.
+
+`topK`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 10
+|===
++
+How many k-nearest results to return.
+
+Here's how to run a KNN search:
+
+[source,text]
+&q={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]
+
+The search results retrieved are the K-nearest to the vector in input `[1.0, 2.0, 3.0, 4.0]`, ranked by the similarityFunction configured at indexing time.
+
+==== Usage with Filter Queries
+The `knn` query parser can be used in filter queries:
+[source,text]
+&q=id:(1 2 3)&fq={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]
+
+The `knn` query parser can be used with filter queries:
+[source,text]
+&q={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]&fq=id:(1 2 3)
+
+[IMPORTANT]
+====
+When using `knn` in these scenarios make sure you have clear how filter queries work in Apache Solr:

Review comment:
       ```suggestion
   When using `knn` in these scenarios make sure you have a clear understanding of how filter queries work in Apache Solr:
   ```

##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,320 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+With the *Neural Search* module Apache Solr is introducing support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not simply be solved by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+
+=== DenseVectorField
+The Dense Vector field gives the possibility of indexing and searching dense vectors of float elements.
+
+e.g.
+
+`[1.0, 2.5, 3.7, 4.1]` (array of float elements)
+
+Here's how `DenseVectorField` should be configured in the schema:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`vectorDimension`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The dimension of the dense vector to pass in.
++
+Accepted values:
+Integer < = 1024.
+
+`similarityFunction`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `euclidean`
+|===
++
+Vector similarity function; used in search to return top K most similar vectors to a target vector.
++
+Accepted values: `euclidean`, `dot_product`  or `cosine`.
+
+* `euclidean`: https://en.wikipedia.org/wiki/Euclidean_distance[Euclidean distance]
+* `dot_product`: https://en.wikipedia.org/wiki/Dot_product[Dot product]. *NOTE*: this similarity is intended as an optimized way to perform cosine similarity. In order to use it, all vectors must be of unit length, including both document and query vectors. Using dot product with vectors that are not unit length can result in errors or poor search results..
+* `cosine`: https://en.wikipedia.org/wiki/Cosine_similarity[Cosine similarity]. *NOTE*: the preferred way to perform cosine similarity is to normalize all vectors to unit length, and instead use DOT_PRODUCT. You should only use this function if you need to preserve the original vectors and cannot normalize them in advance.
+
+*N.B.* To use the following advanced parameters that customise the codec format
+and the hyper-parameter of the HNSW algorithm make sure you set this configuration in the solrconfig.xml:
+[source,xml]
+<config>
+<codecFactory class="solr.SchemaCodecFactory"/>
+...
+
+Here's how `DenseVectorField` can be configured with the advanced codec hyper-parameters:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine" codecFormat="Lucene90HnswVectorsFormat" hnswMaxConnections="10" hnswBeamWidth="40"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`codecFormat`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `Lucene90HnswVectorsFormat`
+|===
++
+(advanced) Specifies the knn codec implementation to use
++
+
+Accepted values: `Lucene90HnswVectorsFormat`.
+
+Please note that the `codecFormat` accepted values may change in future releases.
+
+
+
+[NOTE]
+Lucene index back-compatibility is only supported for the default codec.
+If you choose to customize the `codecFormat` in your schema, upgrading to a future version of Solr may require you to either switch back to the default codec and optimize your index to rewrite it into the default codec before upgrading, or re-build your entire index from scratch after upgrading.
+
+`hnswMaxConnections`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 16
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+Controls how many of the nearest neighbor candidates are connected to the new node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `M` from the later paper.
++
+Accepted values:
+Integer.
+
+`hnswBeamWidth`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 100
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+It is the number of nearest neighbor candidates to track while searching the graph for each newly inserted node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `efConstruction` from the later paper.
++
+Accepted values:
+Integer.
+
+DenseVectorField supports the attributes: `indexed`, `stored`.
+
+*N.B.* currently multivalue is not supported
+
+Here's how a `DenseVectorField` should be indexed:
+
+[.dynamic-tabs]
+--
+[example.tab-pane#json]
+====
+[.tab-label]*JSON*
+[source,json]
+----
+[{ "id": "1",
+"vector": [1.0, 2.5, 3.7, 4.1]
+},
+{ "id": "2",
+"vector": [1.5, 5.5, 6.7, 65.1]
+}
+]
+----
+====
+
+[example.tab-pane#xml]
+====
+[.tab-label]*XML*
+[source,xml]
+----
+<add>
+<doc>
+<field name="id">1</field>
+<field name="vector">1.0</field>
+<field name="vector">2.5</field>
+<field name="vector">3.7</field>
+<field name="vector">4.1</field>
+</doc>
+<doc>
+<field name="id">2</field>
+<field name="vector">1.5</field>
+<field name="vector">5.5</field>
+<field name="vector">6.7</field>
+<field name="vector">65.1</field>
+</doc>
+</add>
+----
+====
+
+[example.tab-pane#solrj]
+====
+[.tab-label]*SolrJ*
+[source,java,indent=0]
+----
+final SolrClient client = getSolrClient();
+
+final SolrInputDocument d1 = new SolrInputDocument();
+d1.setField("id", "1");
+d1.setField("vector", Arrays.asList(1.0f, 2.5f, 3.7f, 4.1f));
+
+
+final SolrInputDocument d2 = new SolrInputDocument();
+d2.setField("id", "2");
+d2.setField("vector", Arrays.asList(1.5f, 5.5f, 6.7f, 65.1f));
+
+client.add(Arrays.asList(d1, d2));
+----
+====
+--
+
+== Query Time
+This is the list of Apache Solr query approaches designed to support Neural Search:
+
+=== knn Query Parser
+The `knn` K-Nearest Neighbors query parser allows to find the k-nearest documents to the target vector according to indexed dense vectors in the given field.
+
+It takes the following parameters:
+
+`f`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The DenseVectorField to search in.
+
+`topK`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 10
+|===
++
+How many k-nearest results to return.
+
+Here's how to run a KNN search:
+
+[source,text]
+&q={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]
+
+The search results retrieved are the K-nearest to the vector in input `[1.0, 2.0, 3.0, 4.0]`, ranked by the similarityFunction configured at indexing time.
+
+==== Usage with Filter Queries
+The `knn` query parser can be used in filter queries:
+[source,text]
+&q=id:(1 2 3)&fq={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]
+
+The `knn` query parser can be used with filter queries:
+[source,text]
+&q={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]&fq=id:(1 2 3)
+
+[IMPORTANT]
+====
+When using `knn` in these scenarios make sure you have clear how filter queries work in Apache Solr:
+
+The Ranked List of document IDs resulting from the main query `q` is intersected with the set of document IDs deriving from each filter query `fq`.
+
+e.g.
+
+Ranked List from `q`=`[ID1, ID4, ID2, ID10]` <intersects> Set from `fq`=`{ID3, ID2, ID9, ID4}` = `[ID4,ID2]`
+====
+
+
+==== Usage as Re-Ranking Query
+The `knn` query parser can be used to rerank first pass query results:
+[source,text]
+&q=id:(3 4 9 2)&rq={!rerank reRankQuery=$rqq reRankDocs=4 reRankWeight=1}&rqq={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]
+
+[IMPORTANT]
+====
+When using `knn` in reranking pay attention to the `topK` parameter.
+
+The second pass score(deriving from knn) is calculated only if the documend `d` from the first pass is within
+the K-nearest neighbors(*in the whole index*) of the target vector to search.
+
+This means the second pass `knn` is executed on the whole index anyway, which is a current limitation.
+
+The final ranked list of results will have the first pass score(main query `q`) combined with the second pass score(the approximated similarityFunction distance to the target vector to search).
+====
+
+== Additional Neural Search Resources
+
+* Apache Solr Dense Vectors

Review comment:
       The two below links aren't valid yet?

##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,320 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+With the *Neural Search* module Apache Solr is introducing support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not simply be solved by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+
+=== DenseVectorField
+The Dense Vector field gives the possibility of indexing and searching dense vectors of float elements.
+
+e.g.
+
+`[1.0, 2.5, 3.7, 4.1]` (array of float elements)
+
+Here's how `DenseVectorField` should be configured in the schema:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`vectorDimension`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The dimension of the dense vector to pass in.
++
+Accepted values:
+Integer < = 1024.
+
+`similarityFunction`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `euclidean`
+|===
++
+Vector similarity function; used in search to return top K most similar vectors to a target vector.
++
+Accepted values: `euclidean`, `dot_product`  or `cosine`.
+
+* `euclidean`: https://en.wikipedia.org/wiki/Euclidean_distance[Euclidean distance]
+* `dot_product`: https://en.wikipedia.org/wiki/Dot_product[Dot product]. *NOTE*: this similarity is intended as an optimized way to perform cosine similarity. In order to use it, all vectors must be of unit length, including both document and query vectors. Using dot product with vectors that are not unit length can result in errors or poor search results..
+* `cosine`: https://en.wikipedia.org/wiki/Cosine_similarity[Cosine similarity]. *NOTE*: the preferred way to perform cosine similarity is to normalize all vectors to unit length, and instead use DOT_PRODUCT. You should only use this function if you need to preserve the original vectors and cannot normalize them in advance.
+
+*N.B.* To use the following advanced parameters that customise the codec format
+and the hyper-parameter of the HNSW algorithm make sure you set this configuration in the solrconfig.xml:
+[source,xml]
+<config>
+<codecFactory class="solr.SchemaCodecFactory"/>
+...
+
+Here's how `DenseVectorField` can be configured with the advanced codec hyper-parameters:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine" codecFormat="Lucene90HnswVectorsFormat" hnswMaxConnections="10" hnswBeamWidth="40"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`codecFormat`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `Lucene90HnswVectorsFormat`
+|===
++
+(advanced) Specifies the knn codec implementation to use
++
+
+Accepted values: `Lucene90HnswVectorsFormat`.
+
+Please note that the `codecFormat` accepted values may change in future releases.
+
+
+
+[NOTE]
+Lucene index back-compatibility is only supported for the default codec.
+If you choose to customize the `codecFormat` in your schema, upgrading to a future version of Solr may require you to either switch back to the default codec and optimize your index to rewrite it into the default codec before upgrading, or re-build your entire index from scratch after upgrading.
+
+`hnswMaxConnections`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 16
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+Controls how many of the nearest neighbor candidates are connected to the new node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `M` from the later paper.
++
+Accepted values:
+Integer.
+
+`hnswBeamWidth`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 100
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+It is the number of nearest neighbor candidates to track while searching the graph for each newly inserted node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `efConstruction` from the later paper.
++
+Accepted values:
+Integer.
+
+DenseVectorField supports the attributes: `indexed`, `stored`.
+
+*N.B.* currently multivalue is not supported
+
+Here's how a `DenseVectorField` should be indexed:
+
+[.dynamic-tabs]
+--
+[example.tab-pane#json]
+====
+[.tab-label]*JSON*
+[source,json]
+----
+[{ "id": "1",
+"vector": [1.0, 2.5, 3.7, 4.1]
+},
+{ "id": "2",
+"vector": [1.5, 5.5, 6.7, 65.1]
+}
+]
+----
+====
+
+[example.tab-pane#xml]
+====
+[.tab-label]*XML*
+[source,xml]
+----
+<add>
+<doc>
+<field name="id">1</field>
+<field name="vector">1.0</field>
+<field name="vector">2.5</field>
+<field name="vector">3.7</field>
+<field name="vector">4.1</field>
+</doc>
+<doc>
+<field name="id">2</field>
+<field name="vector">1.5</field>
+<field name="vector">5.5</field>
+<field name="vector">6.7</field>
+<field name="vector">65.1</field>
+</doc>
+</add>
+----
+====
+
+[example.tab-pane#solrj]
+====
+[.tab-label]*SolrJ*
+[source,java,indent=0]
+----
+final SolrClient client = getSolrClient();
+
+final SolrInputDocument d1 = new SolrInputDocument();
+d1.setField("id", "1");
+d1.setField("vector", Arrays.asList(1.0f, 2.5f, 3.7f, 4.1f));
+
+
+final SolrInputDocument d2 = new SolrInputDocument();
+d2.setField("id", "2");
+d2.setField("vector", Arrays.asList(1.5f, 5.5f, 6.7f, 65.1f));
+
+client.add(Arrays.asList(d1, d2));
+----
+====
+--
+
+== Query Time
+This is the list of Apache Solr query approaches designed to support Neural Search:
+
+=== knn Query Parser
+The `knn` K-Nearest Neighbors query parser allows to find the k-nearest documents to the target vector according to indexed dense vectors in the given field.
+
+It takes the following parameters:
+
+`f`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The DenseVectorField to search in.
+
+`topK`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 10
+|===
++
+How many k-nearest results to return.
+
+Here's how to run a KNN search:
+
+[source,text]
+&q={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]
+
+The search results retrieved are the K-nearest to the vector in input `[1.0, 2.0, 3.0, 4.0]`, ranked by the similarityFunction configured at indexing time.
+
+==== Usage with Filter Queries
+The `knn` query parser can be used in filter queries:
+[source,text]
+&q=id:(1 2 3)&fq={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]
+
+The `knn` query parser can be used with filter queries:
+[source,text]
+&q={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]&fq=id:(1 2 3)
+
+[IMPORTANT]
+====
+When using `knn` in these scenarios make sure you have clear how filter queries work in Apache Solr:
+
+The Ranked List of document IDs resulting from the main query `q` is intersected with the set of document IDs deriving from each filter query `fq`.
+
+e.g.
+
+Ranked List from `q`=`[ID1, ID4, ID2, ID10]` <intersects> Set from `fq`=`{ID3, ID2, ID9, ID4}` = `[ID4,ID2]`
+====
+
+
+==== Usage as Re-Ranking Query
+The `knn` query parser can be used to rerank first pass query results:
+[source,text]
+&q=id:(3 4 9 2)&rq={!rerank reRankQuery=$rqq reRankDocs=4 reRankWeight=1}&rqq={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]
+
+[IMPORTANT]
+====
+When using `knn` in reranking pay attention to the `topK` parameter.
+
+The second pass score(deriving from knn) is calculated only if the documend `d` from the first pass is within
+the K-nearest neighbors(*in the whole index*) of the target vector to search.
+
+This means the second pass `knn` is executed on the whole index anyway, which is a current limitation.
+
+The final ranked list of results will have the first pass score(main query `q`) combined with the second pass score(the approximated similarityFunction distance to the target vector to search).

Review comment:
       Maybe this is understood if you understand reranked queries, but what does `combined with` mean here? Can `combined with` be more explicit - ie: added to, multiplied by, replaced by, etc?

##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,320 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+With the *Neural Search* module Apache Solr is introducing support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not simply be solved by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+
+=== DenseVectorField
+The Dense Vector field gives the possibility of indexing and searching dense vectors of float elements.
+
+e.g.
+
+`[1.0, 2.5, 3.7, 4.1]` (array of float elements)
+
+Here's how `DenseVectorField` should be configured in the schema:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`vectorDimension`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The dimension of the dense vector to pass in.
++
+Accepted values:
+Integer < = 1024.
+
+`similarityFunction`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `euclidean`
+|===
++
+Vector similarity function; used in search to return top K most similar vectors to a target vector.
++
+Accepted values: `euclidean`, `dot_product`  or `cosine`.
+
+* `euclidean`: https://en.wikipedia.org/wiki/Euclidean_distance[Euclidean distance]
+* `dot_product`: https://en.wikipedia.org/wiki/Dot_product[Dot product]. *NOTE*: this similarity is intended as an optimized way to perform cosine similarity. In order to use it, all vectors must be of unit length, including both document and query vectors. Using dot product with vectors that are not unit length can result in errors or poor search results..
+* `cosine`: https://en.wikipedia.org/wiki/Cosine_similarity[Cosine similarity]. *NOTE*: the preferred way to perform cosine similarity is to normalize all vectors to unit length, and instead use DOT_PRODUCT. You should only use this function if you need to preserve the original vectors and cannot normalize them in advance.
+
+*N.B.* To use the following advanced parameters that customise the codec format
+and the hyper-parameter of the HNSW algorithm make sure you set this configuration in the solrconfig.xml:
+[source,xml]
+<config>
+<codecFactory class="solr.SchemaCodecFactory"/>
+...
+
+Here's how `DenseVectorField` can be configured with the advanced codec hyper-parameters:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine" codecFormat="Lucene90HnswVectorsFormat" hnswMaxConnections="10" hnswBeamWidth="40"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`codecFormat`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `Lucene90HnswVectorsFormat`
+|===
++
+(advanced) Specifies the knn codec implementation to use
++
+
+Accepted values: `Lucene90HnswVectorsFormat`.
+
+Please note that the `codecFormat` accepted values may change in future releases.
+
+
+
+[NOTE]
+Lucene index back-compatibility is only supported for the default codec.
+If you choose to customize the `codecFormat` in your schema, upgrading to a future version of Solr may require you to either switch back to the default codec and optimize your index to rewrite it into the default codec before upgrading, or re-build your entire index from scratch after upgrading.
+
+`hnswMaxConnections`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 16
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+Controls how many of the nearest neighbor candidates are connected to the new node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `M` from the later paper.
++
+Accepted values:
+Integer.
+
+`hnswBeamWidth`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 100
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+It is the number of nearest neighbor candidates to track while searching the graph for each newly inserted node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `efConstruction` from the later paper.
++
+Accepted values:
+Integer.
+
+DenseVectorField supports the attributes: `indexed`, `stored`.
+
+*N.B.* currently multivalue is not supported
+
+Here's how a `DenseVectorField` should be indexed:
+
+[.dynamic-tabs]
+--
+[example.tab-pane#json]
+====
+[.tab-label]*JSON*
+[source,json]
+----
+[{ "id": "1",
+"vector": [1.0, 2.5, 3.7, 4.1]
+},
+{ "id": "2",
+"vector": [1.5, 5.5, 6.7, 65.1]
+}
+]
+----
+====
+
+[example.tab-pane#xml]
+====
+[.tab-label]*XML*
+[source,xml]
+----
+<add>
+<doc>
+<field name="id">1</field>
+<field name="vector">1.0</field>
+<field name="vector">2.5</field>
+<field name="vector">3.7</field>
+<field name="vector">4.1</field>
+</doc>
+<doc>
+<field name="id">2</field>
+<field name="vector">1.5</field>
+<field name="vector">5.5</field>
+<field name="vector">6.7</field>
+<field name="vector">65.1</field>
+</doc>
+</add>
+----
+====
+
+[example.tab-pane#solrj]
+====
+[.tab-label]*SolrJ*
+[source,java,indent=0]
+----
+final SolrClient client = getSolrClient();
+
+final SolrInputDocument d1 = new SolrInputDocument();
+d1.setField("id", "1");
+d1.setField("vector", Arrays.asList(1.0f, 2.5f, 3.7f, 4.1f));
+
+
+final SolrInputDocument d2 = new SolrInputDocument();
+d2.setField("id", "2");
+d2.setField("vector", Arrays.asList(1.5f, 5.5f, 6.7f, 65.1f));
+
+client.add(Arrays.asList(d1, d2));
+----
+====
+--
+
+== Query Time
+This is the list of Apache Solr query approaches designed to support Neural Search:
+
+=== knn Query Parser
+The `knn` K-Nearest Neighbors query parser allows to find the k-nearest documents to the target vector according to indexed dense vectors in the given field.
+
+It takes the following parameters:
+
+`f`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The DenseVectorField to search in.
+
+`topK`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 10
+|===
++
+How many k-nearest results to return.
+
+Here's how to run a KNN search:
+
+[source,text]
+&q={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]
+
+The search results retrieved are the K-nearest to the vector in input `[1.0, 2.0, 3.0, 4.0]`, ranked by the similarityFunction configured at indexing time.

Review comment:
       I'm not super familiar with neural search, but does the `similarityFunction` need to be defined at index time? In my head the math to compare vectors happens at query time - so the similarityFunction should be definable at query time?
   
   I saw the note above about there are limitations of what `similarityFunction` is used based on how the vector values are indexed (ie: unit length vectors), but it doesn't sound like checking the types of vectors is enforced at index time. If the check of type of vectors was done at index time, then I can see why `similarityFunction` should be defined at index time instead of query time.

##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,320 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+With the *Neural Search* module Apache Solr is introducing support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not simply be solved by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+
+=== DenseVectorField
+The Dense Vector field gives the possibility of indexing and searching dense vectors of float elements.
+
+e.g.
+
+`[1.0, 2.5, 3.7, 4.1]` (array of float elements)
+
+Here's how `DenseVectorField` should be configured in the schema:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`vectorDimension`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The dimension of the dense vector to pass in.
++
+Accepted values:
+Integer < = 1024.
+
+`similarityFunction`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `euclidean`
+|===
++
+Vector similarity function; used in search to return top K most similar vectors to a target vector.
++
+Accepted values: `euclidean`, `dot_product`  or `cosine`.
+
+* `euclidean`: https://en.wikipedia.org/wiki/Euclidean_distance[Euclidean distance]
+* `dot_product`: https://en.wikipedia.org/wiki/Dot_product[Dot product]. *NOTE*: this similarity is intended as an optimized way to perform cosine similarity. In order to use it, all vectors must be of unit length, including both document and query vectors. Using dot product with vectors that are not unit length can result in errors or poor search results..
+* `cosine`: https://en.wikipedia.org/wiki/Cosine_similarity[Cosine similarity]. *NOTE*: the preferred way to perform cosine similarity is to normalize all vectors to unit length, and instead use DOT_PRODUCT. You should only use this function if you need to preserve the original vectors and cannot normalize them in advance.
+
+*N.B.* To use the following advanced parameters that customise the codec format
+and the hyper-parameter of the HNSW algorithm make sure you set this configuration in the solrconfig.xml:
+[source,xml]
+<config>
+<codecFactory class="solr.SchemaCodecFactory"/>
+...
+
+Here's how `DenseVectorField` can be configured with the advanced codec hyper-parameters:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine" codecFormat="Lucene90HnswVectorsFormat" hnswMaxConnections="10" hnswBeamWidth="40"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`codecFormat`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `Lucene90HnswVectorsFormat`
+|===
++
+(advanced) Specifies the knn codec implementation to use
++
+
+Accepted values: `Lucene90HnswVectorsFormat`.
+
+Please note that the `codecFormat` accepted values may change in future releases.
+
+
+
+[NOTE]
+Lucene index back-compatibility is only supported for the default codec.
+If you choose to customize the `codecFormat` in your schema, upgrading to a future version of Solr may require you to either switch back to the default codec and optimize your index to rewrite it into the default codec before upgrading, or re-build your entire index from scratch after upgrading.
+
+`hnswMaxConnections`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 16
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+Controls how many of the nearest neighbor candidates are connected to the new node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `M` from the later paper.
++
+Accepted values:
+Integer.
+
+`hnswBeamWidth`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 100
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+It is the number of nearest neighbor candidates to track while searching the graph for each newly inserted node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `efConstruction` from the later paper.
++
+Accepted values:
+Integer.
+
+DenseVectorField supports the attributes: `indexed`, `stored`.
+
+*N.B.* currently multivalue is not supported
+
+Here's how a `DenseVectorField` should be indexed:
+
+[.dynamic-tabs]
+--
+[example.tab-pane#json]
+====
+[.tab-label]*JSON*
+[source,json]
+----
+[{ "id": "1",
+"vector": [1.0, 2.5, 3.7, 4.1]
+},
+{ "id": "2",
+"vector": [1.5, 5.5, 6.7, 65.1]
+}
+]
+----
+====
+
+[example.tab-pane#xml]
+====
+[.tab-label]*XML*
+[source,xml]
+----
+<add>
+<doc>
+<field name="id">1</field>
+<field name="vector">1.0</field>
+<field name="vector">2.5</field>
+<field name="vector">3.7</field>
+<field name="vector">4.1</field>
+</doc>
+<doc>
+<field name="id">2</field>
+<field name="vector">1.5</field>
+<field name="vector">5.5</field>
+<field name="vector">6.7</field>
+<field name="vector">65.1</field>
+</doc>
+</add>
+----
+====
+
+[example.tab-pane#solrj]
+====
+[.tab-label]*SolrJ*
+[source,java,indent=0]
+----
+final SolrClient client = getSolrClient();
+
+final SolrInputDocument d1 = new SolrInputDocument();
+d1.setField("id", "1");
+d1.setField("vector", Arrays.asList(1.0f, 2.5f, 3.7f, 4.1f));
+
+
+final SolrInputDocument d2 = new SolrInputDocument();
+d2.setField("id", "2");
+d2.setField("vector", Arrays.asList(1.5f, 5.5f, 6.7f, 65.1f));
+
+client.add(Arrays.asList(d1, d2));
+----
+====
+--
+
+== Query Time
+This is the list of Apache Solr query approaches designed to support Neural Search:
+
+=== knn Query Parser
+The `knn` K-Nearest Neighbors query parser allows to find the k-nearest documents to the target vector according to indexed dense vectors in the given field.
+
+It takes the following parameters:
+
+`f`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The DenseVectorField to search in.
+
+`topK`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 10
+|===
++
+How many k-nearest results to return.
+
+Here's how to run a KNN search:
+
+[source,text]
+&q={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]
+
+The search results retrieved are the K-nearest to the vector in input `[1.0, 2.0, 3.0, 4.0]`, ranked by the similarityFunction configured at indexing time.
+
+==== Usage with Filter Queries
+The `knn` query parser can be used in filter queries:
+[source,text]
+&q=id:(1 2 3)&fq={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]
+
+The `knn` query parser can be used with filter queries:
+[source,text]
+&q={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]&fq=id:(1 2 3)
+
+[IMPORTANT]
+====
+When using `knn` in these scenarios make sure you have clear how filter queries work in Apache Solr:
+
+The Ranked List of document IDs resulting from the main query `q` is intersected with the set of document IDs deriving from each filter query `fq`.
+
+e.g.
+
+Ranked List from `q`=`[ID1, ID4, ID2, ID10]` <intersects> Set from `fq`=`{ID3, ID2, ID9, ID4}` = `[ID4,ID2]`
+====
+
+
+==== Usage as Re-Ranking Query
+The `knn` query parser can be used to rerank first pass query results:
+[source,text]
+&q=id:(3 4 9 2)&rq={!rerank reRankQuery=$rqq reRankDocs=4 reRankWeight=1}&rqq={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]
+
+[IMPORTANT]
+====
+When using `knn` in reranking pay attention to the `topK` parameter.
+
+The second pass score(deriving from knn) is calculated only if the documend `d` from the first pass is within
+the K-nearest neighbors(*in the whole index*) of the target vector to search.
+
+This means the second pass `knn` is executed on the whole index anyway, which is a current limitation.

Review comment:
       `which is a current limitation.` - is there a Jira to potentially link to an improvement here?

##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,320 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+With the *Neural Search* module Apache Solr is introducing support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not simply be solved by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+
+=== DenseVectorField
+The Dense Vector field gives the possibility of indexing and searching dense vectors of float elements.
+
+e.g.
+
+`[1.0, 2.5, 3.7, 4.1]` (array of float elements)
+
+Here's how `DenseVectorField` should be configured in the schema:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`vectorDimension`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The dimension of the dense vector to pass in.
++
+Accepted values:
+Integer < = 1024.
+
+`similarityFunction`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `euclidean`
+|===
++
+Vector similarity function; used in search to return top K most similar vectors to a target vector.
++
+Accepted values: `euclidean`, `dot_product`  or `cosine`.
+
+* `euclidean`: https://en.wikipedia.org/wiki/Euclidean_distance[Euclidean distance]
+* `dot_product`: https://en.wikipedia.org/wiki/Dot_product[Dot product]. *NOTE*: this similarity is intended as an optimized way to perform cosine similarity. In order to use it, all vectors must be of unit length, including both document and query vectors. Using dot product with vectors that are not unit length can result in errors or poor search results..
+* `cosine`: https://en.wikipedia.org/wiki/Cosine_similarity[Cosine similarity]. *NOTE*: the preferred way to perform cosine similarity is to normalize all vectors to unit length, and instead use DOT_PRODUCT. You should only use this function if you need to preserve the original vectors and cannot normalize them in advance.
+
+*N.B.* To use the following advanced parameters that customise the codec format
+and the hyper-parameter of the HNSW algorithm make sure you set this configuration in the solrconfig.xml:
+[source,xml]
+<config>
+<codecFactory class="solr.SchemaCodecFactory"/>
+...
+
+Here's how `DenseVectorField` can be configured with the advanced codec hyper-parameters:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine" codecFormat="Lucene90HnswVectorsFormat" hnswMaxConnections="10" hnswBeamWidth="40"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`codecFormat`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `Lucene90HnswVectorsFormat`
+|===
++
+(advanced) Specifies the knn codec implementation to use
++
+
+Accepted values: `Lucene90HnswVectorsFormat`.
+
+Please note that the `codecFormat` accepted values may change in future releases.
+
+
+
+[NOTE]
+Lucene index back-compatibility is only supported for the default codec.
+If you choose to customize the `codecFormat` in your schema, upgrading to a future version of Solr may require you to either switch back to the default codec and optimize your index to rewrite it into the default codec before upgrading, or re-build your entire index from scratch after upgrading.
+
+`hnswMaxConnections`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 16
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+Controls how many of the nearest neighbor candidates are connected to the new node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `M` from the later paper.
++
+Accepted values:
+Integer.
+
+`hnswBeamWidth`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 100
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+It is the number of nearest neighbor candidates to track while searching the graph for each newly inserted node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `efConstruction` from the later paper.
++
+Accepted values:
+Integer.
+
+DenseVectorField supports the attributes: `indexed`, `stored`.
+
+*N.B.* currently multivalue is not supported
+
+Here's how a `DenseVectorField` should be indexed:
+
+[.dynamic-tabs]
+--
+[example.tab-pane#json]
+====
+[.tab-label]*JSON*
+[source,json]
+----
+[{ "id": "1",
+"vector": [1.0, 2.5, 3.7, 4.1]
+},
+{ "id": "2",
+"vector": [1.5, 5.5, 6.7, 65.1]
+}
+]
+----
+====
+
+[example.tab-pane#xml]
+====
+[.tab-label]*XML*
+[source,xml]
+----
+<add>
+<doc>
+<field name="id">1</field>
+<field name="vector">1.0</field>
+<field name="vector">2.5</field>
+<field name="vector">3.7</field>
+<field name="vector">4.1</field>
+</doc>
+<doc>
+<field name="id">2</field>
+<field name="vector">1.5</field>
+<field name="vector">5.5</field>
+<field name="vector">6.7</field>
+<field name="vector">65.1</field>
+</doc>
+</add>
+----
+====
+
+[example.tab-pane#solrj]
+====
+[.tab-label]*SolrJ*
+[source,java,indent=0]
+----
+final SolrClient client = getSolrClient();
+
+final SolrInputDocument d1 = new SolrInputDocument();
+d1.setField("id", "1");
+d1.setField("vector", Arrays.asList(1.0f, 2.5f, 3.7f, 4.1f));
+
+
+final SolrInputDocument d2 = new SolrInputDocument();
+d2.setField("id", "2");
+d2.setField("vector", Arrays.asList(1.5f, 5.5f, 6.7f, 65.1f));
+
+client.add(Arrays.asList(d1, d2));
+----
+====
+--
+
+== Query Time
+This is the list of Apache Solr query approaches designed to support Neural Search:
+
+=== knn Query Parser
+The `knn` K-Nearest Neighbors query parser allows to find the k-nearest documents to the target vector according to indexed dense vectors in the given field.
+
+It takes the following parameters:
+
+`f`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The DenseVectorField to search in.
+
+`topK`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 10
+|===
++
+How many k-nearest results to return.
+
+Here's how to run a KNN search:
+
+[source,text]
+&q={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]
+
+The search results retrieved are the K-nearest to the vector in input `[1.0, 2.0, 3.0, 4.0]`, ranked by the similarityFunction configured at indexing time.
+
+==== Usage with Filter Queries
+The `knn` query parser can be used in filter queries:
+[source,text]
+&q=id:(1 2 3)&fq={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]
+
+The `knn` query parser can be used with filter queries:
+[source,text]
+&q={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]&fq=id:(1 2 3)
+
+[IMPORTANT]
+====
+When using `knn` in these scenarios make sure you have clear how filter queries work in Apache Solr:
+
+The Ranked List of document IDs resulting from the main query `q` is intersected with the set of document IDs deriving from each filter query `fq`.
+
+e.g.
+
+Ranked List from `q`=`[ID1, ID4, ID2, ID10]` <intersects> Set from `fq`=`{ID3, ID2, ID9, ID4}` = `[ID4,ID2]`
+====
+
+
+==== Usage as Re-Ranking Query
+The `knn` query parser can be used to rerank first pass query results:
+[source,text]
+&q=id:(3 4 9 2)&rq={!rerank reRankQuery=$rqq reRankDocs=4 reRankWeight=1}&rqq={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]
+
+[IMPORTANT]
+====
+When using `knn` in reranking pay attention to the `topK` parameter.
+
+The second pass score(deriving from knn) is calculated only if the documend `d` from the first pass is within

Review comment:
       ```suggestion
   The second pass score(deriving from knn) is calculated only if the document `d` from the first pass is within
   ```

##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,320 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+With the *Neural Search* module Apache Solr is introducing support for neural networks based techniques that can improve various aspects of search.

Review comment:
       ```suggestion
   With the *Neural Search* module Apache Solr is support for neural networks based techniques that can improve various aspects of search.
   ```




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r783009093



##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,320 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+With the *Neural Search* module Apache Solr is introducing support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not simply be solved by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+
+=== DenseVectorField
+The Dense Vector field gives the possibility of indexing and searching dense vectors of float elements.
+
+e.g.
+
+`[1.0, 2.5, 3.7, 4.1]` (array of float elements)
+
+Here's how `DenseVectorField` should be configured in the schema:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`vectorDimension`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The dimension of the dense vector to pass in.
++
+Accepted values:
+Integer < = 1024.
+
+`similarityFunction`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `euclidean`
+|===
++
+Vector similarity function; used in search to return top K most similar vectors to a target vector.
++
+Accepted values: `euclidean`, `dot_product`  or `cosine`.
+
+* `euclidean`: https://en.wikipedia.org/wiki/Euclidean_distance[Euclidean distance]
+* `dot_product`: https://en.wikipedia.org/wiki/Dot_product[Dot product]. *NOTE*: this similarity is intended as an optimized way to perform cosine similarity. In order to use it, all vectors must be of unit length, including both document and query vectors. Using dot product with vectors that are not unit length can result in errors or poor search results..
+* `cosine`: https://en.wikipedia.org/wiki/Cosine_similarity[Cosine similarity]. *NOTE*: the preferred way to perform cosine similarity is to normalize all vectors to unit length, and instead use DOT_PRODUCT. You should only use this function if you need to preserve the original vectors and cannot normalize them in advance.
+
+*N.B.* To use the following advanced parameters that customise the codec format
+and the hyper-parameter of the HNSW algorithm make sure you set this configuration in the solrconfig.xml:
+[source,xml]
+<config>
+<codecFactory class="solr.SchemaCodecFactory"/>
+...
+
+Here's how `DenseVectorField` can be configured with the advanced codec hyper-parameters:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine" codecFormat="Lucene90HnswVectorsFormat" hnswMaxConnections="10" hnswBeamWidth="40"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`codecFormat`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `Lucene90HnswVectorsFormat`
+|===
++
+(advanced) Specifies the knn codec implementation to use
++
+
+Accepted values: `Lucene90HnswVectorsFormat`.
+
+Please note that the `codecFormat` accepted values may change in future releases.
+
+
+
+[NOTE]
+Lucene index back-compatibility is only supported for the default codec.
+If you choose to customize the `codecFormat` in your schema, upgrading to a future version of Solr may require you to either switch back to the default codec and optimize your index to rewrite it into the default codec before upgrading, or re-build your entire index from scratch after upgrading.
+
+`hnswMaxConnections`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 16
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+Controls how many of the nearest neighbor candidates are connected to the new node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `M` from the later paper.
++
+Accepted values:
+Integer.
+
+`hnswBeamWidth`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 100
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+It is the number of nearest neighbor candidates to track while searching the graph for each newly inserted node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `efConstruction` from the later paper.
++
+Accepted values:
+Integer.
+
+DenseVectorField supports the attributes: `indexed`, `stored`.
+
+*N.B.* currently multivalue is not supported
+
+Here's how a `DenseVectorField` should be indexed:
+
+[.dynamic-tabs]
+--
+[example.tab-pane#json]
+====
+[.tab-label]*JSON*
+[source,json]
+----
+[{ "id": "1",
+"vector": [1.0, 2.5, 3.7, 4.1]
+},
+{ "id": "2",
+"vector": [1.5, 5.5, 6.7, 65.1]
+}
+]
+----
+====
+
+[example.tab-pane#xml]
+====
+[.tab-label]*XML*
+[source,xml]
+----
+<add>
+<doc>
+<field name="id">1</field>
+<field name="vector">1.0</field>
+<field name="vector">2.5</field>
+<field name="vector">3.7</field>
+<field name="vector">4.1</field>
+</doc>
+<doc>
+<field name="id">2</field>
+<field name="vector">1.5</field>
+<field name="vector">5.5</field>
+<field name="vector">6.7</field>
+<field name="vector">65.1</field>
+</doc>
+</add>
+----
+====
+
+[example.tab-pane#solrj]
+====
+[.tab-label]*SolrJ*
+[source,java,indent=0]
+----
+final SolrClient client = getSolrClient();
+
+final SolrInputDocument d1 = new SolrInputDocument();
+d1.setField("id", "1");
+d1.setField("vector", Arrays.asList(1.0f, 2.5f, 3.7f, 4.1f));
+
+
+final SolrInputDocument d2 = new SolrInputDocument();
+d2.setField("id", "2");
+d2.setField("vector", Arrays.asList(1.5f, 5.5f, 6.7f, 65.1f));
+
+client.add(Arrays.asList(d1, d2));
+----
+====
+--
+
+== Query Time
+This is the list of Apache Solr query approaches designed to support Neural Search:
+
+=== knn Query Parser
+The `knn` K-Nearest Neighbors query parser allows to find the k-nearest documents to the target vector according to indexed dense vectors in the given field.
+
+It takes the following parameters:
+
+`f`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The DenseVectorField to search in.
+
+`topK`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 10
+|===
++
+How many k-nearest results to return.
+
+Here's how to run a KNN search:
+
+[source,text]
+&q={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]
+
+The search results retrieved are the K-nearest to the vector in input `[1.0, 2.0, 3.0, 4.0]`, ranked by the similarityFunction configured at indexing time.

Review comment:
       Hi Kevin,
   K-Nearest Neighbor in Apache Solr is backed by the Apache Lucene Approximate Nearest Neighbor implementation based on Hierarchical Navigable Small World Graph (you have the reference to the papers, in this contribution as well and in Lucene source code).
   It's approximate and it relies on building index time graphs that are specific to the similarity(vector distance) function decided.
   
   The Apache Solr org.apache.solr.schema.DenseVectorField builds the Lucene org.apache.lucene.document.KnnVectorField that requires the SimilarityFunction at index time.
   The similarity function is used by the org.apache.lucene.codecs.lucene90.Lucene90HnswVectorsFormat in the 
   org.apache.lucene.codecs.lucene90.Lucene90HnswVectorsWriter#writeGraph method.
   The information is present in the org.apache.lucene.index.FieldInfo org.apache.lucene.index.FieldInfo#getVectorSimilarityFunction, passed by org.apache.lucene.index.IndexingChain#initializeFieldInfo and fetched by org.apache.lucene.index.IndexingChain.FieldSchema.
   In the FieldSchema the property is set by org/apache/lucene/index/IndexingChain.java:827 from the org.apache.lucene.index.IndexableFieldType implementation org.apache.lucene.document.FieldType#setVectorDimensionsAndSimilarityFunction.
   And with that method we reconnect to the org.apache.lucene.document.KnnVectorField#createType.
   Sorry for the long post, but I hope it helps in the comprehension.




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] joel-bernstein commented on a change in pull request #476: SOLR-15880

Posted by GitBox <gi...@apache.org>.
joel-bernstein commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r786285685



##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,322 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.

Review comment:
       I'll add this for sure. This is the now the key machine learning feature and its fits quite nicely with Streaming Expressions and math expressions.




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r786770913



##########
File path: solr/core/src/java/org/apache/solr/update/DocumentBuilder.java
##########
@@ -258,6 +246,48 @@ public static Document toDocument(SolrInputDocument doc, IndexSchema schema, boo
     return out;
   }
 
+  private static boolean addOriginalField( Object originalFieldValue, SchemaField sfield, boolean forInPlaceUpdate, Document out, Set<String> usedFields) {
+    addField(out, sfield, originalFieldValue, forInPlaceUpdate);
+    // record the field as having a value
+    usedFields.add(sfield.getName());
+    return true;
+  }
+
+  private static boolean addCopyFields(Object originalFieldValue, FieldType originalFieldType, List<CopyField> copyFields, boolean forInPlaceUpdate, String uniqueKeyFieldName, Document out, Set<String> usedFields) {
+    boolean used = false;
+    for (CopyField cf : copyFields) {
+      SchemaField destinationField = cf.getDestination();
+
+      final boolean destHasValues = usedFields.contains(destinationField.getName());
+
+      // Dense Vector Fields can only be copied to same field type
+      if (originalFieldType instanceof DenseVectorField && !(destinationField.getType() instanceof DenseVectorField)) {
+        throw new SolrException(SolrException.ErrorCode.BAD_REQUEST,
+                "The copy field destination must be a DenseVectorField: " +
+                        destinationField.getName());
+      }

Review comment:
       Yes, you'll get an exception telling that, just added the test!




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880: K Nearest Neighbors Search

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r787682358



##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+

Review comment:
       Done!




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] ctargett commented on a change in pull request #476: SOLR-15880: K Nearest Neighbors Search

Posted by GitBox <gi...@apache.org>.
ctargett commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r787795388



##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,733 @@
+= Neural Search

Review comment:
       I put this in Slack, here's my take on it:
   
   I have no objection to calling our dense vector support a neural search feature. To be clear, my objection is naming the entire page neural search when there is only one feature described and no indication whatsoever what other features might be or when they may arrive. Seriously, I didn’t see one thing on that page that’s about anything other than dense vectors.
   
   Of course it’s all right that Solr does not have several neural search features right now. Just as it’s all right we don’t yet have any number of other features. To use a parallel example, LTR is a machine learning feature, but we did not name the page “Machine Learning”; we named the page for exactly the feature. It doesn’t knock against LTR that the page isn’t titled “Machine Learning” nor diminish its significance as a feature.
   
   The Ref Guide is not a marketing document - write a news item or a page in the website to promote this functionality when it is released. Call it “Neural Search Comes to Solr” if you want (and you should!). But the Ref Guide must be clear and direct. It is meant for our users to know *exactly* what they need to do to configure Solr to take advantage of the features. I recently renamed dozens of pages and the guiding principle was to make them named for the exact functionality described on the page to make it clear to readers before they even click the title what they can expect to find there.
   
   SolrCloud and Neural Search can be analogous, as large concepts that have several features. But dense vectors is a single feature. When there is more than one, we can talk about an overarching section that brings all the features together but we aren’t there yet at all.




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti edited a comment on pull request #476: SOLR-15880: K Nearest Neighbors Search

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti edited a comment on pull request #476:
URL: https://github.com/apache/solr/pull/476#issuecomment-1016657387


   I refactored the documentation contribution, changing the name of the section to "Dense Vector Search".
   Whenever in the future we add some additional neural search techniques, we can add a parent section that contains the various children.
   I'll wait some additional hours to gather additional feedback, especially for the documentation (thanks @ctargett again for your time).
   
   If no blockers, I'll proceed tomorrow with the merge!


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on pull request #476: SOLR-15880

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on pull request #476:
URL: https://github.com/apache/solr/pull/476#issuecomment-1000895545


   The Pull Request is now complete and ready for review.
   Adding @ctargett  to the loop as there are plenty of documentation additions.
   Merry Christmas :D 


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r776981738



##########
File path: solr/core/src/java/org/apache/solr/search/neural/KnnQParser.java
##########
@@ -0,0 +1,100 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.solr.search.neural;
+
+import org.apache.lucene.search.Query;
+import org.apache.solr.common.SolrException;
+import org.apache.solr.common.params.SolrParams;
+import org.apache.solr.request.SolrQueryRequest;
+import org.apache.solr.schema.DenseVectorField;
+import org.apache.solr.schema.FieldType;
+import org.apache.solr.schema.SchemaField;
+import org.apache.solr.search.QParser;
+import org.apache.solr.search.QueryParsing;
+
+public class KnnQParser extends QParser {
+
+    static final String TOP_K = "topK";// retrieve the top K results based on the distance similarity function 
+    static final int DEFAULT_TOP_K = 10;
+
+    /**
+     * Constructor for the QParser
+     *
+     * @param qstr        The part of the query string specific to this parser
+     * @param localParams The set of parameters that are specific to this QParser.  See https://solr.apache.org/guide/local-parameters-in-queries.html
+     * @param params      The rest of the {@link SolrParams}
+     * @param req         The original {@link SolrQueryRequest}.
+     */
+    public KnnQParser(String qstr, SolrParams localParams, SolrParams params, SolrQueryRequest req) {
+        super(qstr, localParams, params, req);
+    }
+
+    @Override
+    public Query parse() {
+        String denseVectorField = localParams.get(QueryParsing.F);
+        String vectorToSearch = localParams.get(QueryParsing.V);
+        int topK = localParams.getInt(TOP_K, DEFAULT_TOP_K);
+
+        if (denseVectorField == null || denseVectorField.isEmpty()) {
+            throw new SolrException(SolrException.ErrorCode.BAD_REQUEST, "the Dense Vector field 'f' is missing");
+        }
+
+        if (vectorToSearch == null || vectorToSearch.isEmpty()) {
+            throw new SolrException(SolrException.ErrorCode.BAD_REQUEST, "the Dense Vector to search is missing");
+        }
+
+        SchemaField schemaField = req.getCore().getLatestSchema().getField(denseVectorField);
+        FieldType fieldType = schemaField.getType();
+        if (!(fieldType instanceof DenseVectorField)) {
+            throw new SolrException(SolrException.ErrorCode.BAD_REQUEST, "only DenseVectorField is compatible with Knn Query Parser");
+        }
+
+        DenseVectorField denseVectorType = (DenseVectorField) fieldType;
+        float[] parsedVectorToSearch = parseVector(vectorToSearch, denseVectorType.getDimension());
+        return denseVectorType.getKnnVectorQuery(schemaField, parsedVectorToSearch, topK);
+    }
+
+    /**
+     * Parses a String vector.
+     *
+     * @param value with format: [f1, f2, f3, f4...fn]
+     * @return a float array
+     */
+    private float[] parseVector(String value, int dimension) {
+        if (!value.startsWith("[") || !value.endsWith("]")) {
+            throw new SolrException(SolrException.ErrorCode.BAD_REQUEST, "incorrect vector format." +
+                    " The expected format is:'[f1,f2..f3]' where each element f is a float");
+        }
+
+        String[] elements = value.substring(1, value.length() - 1).split(",");

Review comment:
       I checked and the .split("regex") method is used hundreds of times in the Apache Solr codebase, unless any further observations I am resolving this comment.




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] stefan-it commented on pull request #476: SOLR-15880: K Nearest Neighbors Search

Posted by GitBox <gi...@apache.org>.
stefan-it commented on pull request #476:
URL: https://github.com/apache/solr/pull/476#issuecomment-1029096751


   I'm currently using 2048, but I can use a smaller model that outputs 1024 :)


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880: K Nearest Neighbors Search

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r787619052



##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+

Review comment:
       Coming from blogs and paper background, I always try to make a piece of text as "self contained" as possible, thanks for the suggestion, I removed that!




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880: K Nearest Neighbors Search

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r787660168



##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not be solved simply by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+
+=== DenseVectorField
+The Dense Vector field gives the possibility of indexing and searching dense vectors of float elements.
+
+e.g.
+
+`[1.0, 2.5, 3.7, 4.1]` (array of float elements)
+
+Here's how `DenseVectorField` should be configured in the schema:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`vectorDimension`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The dimension of the dense vector to pass in.
++
+Accepted values:
+Integer < = 1024.
+
+`similarityFunction`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `euclidean`
+|===
++
+Vector similarity function; used in search to return top K most similar vectors to a target vector.
++
+Accepted values: `euclidean`, `dot_product`  or `cosine`.
+
+* `euclidean`: https://en.wikipedia.org/wiki/Euclidean_distance[Euclidean distance]
+* `dot_product`: https://en.wikipedia.org/wiki/Dot_product[Dot product]. *NOTE*: this similarity is intended as an optimized way to perform cosine similarity. In order to use it, all vectors must be of unit length, including both document and query vectors. Using dot product with vectors that are not unit length can result in errors or poor search results..
+* `cosine`: https://en.wikipedia.org/wiki/Cosine_similarity[Cosine similarity]. *NOTE*: the preferred way to perform cosine similarity is to normalize all vectors to unit length, and instead use DOT_PRODUCT. You should only use this function if you need to preserve the original vectors and cannot normalize them in advance.
+
+*N.B.* To use the following advanced parameters that customise the codec format
+and the hyper-parameter of the HNSW algorithm make sure you set this configuration in the solrconfig.xml:
+[source,xml]
+<config>
+<codecFactory class="solr.SchemaCodecFactory"/>
+...
+
+Here's how `DenseVectorField` can be configured with the advanced codec hyper-parameters:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine" codecFormat="Lucene90HnswVectorsFormat" hnswMaxConnections="10" hnswBeamWidth="40"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`codecFormat`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `Lucene90HnswVectorsFormat`
+|===
++
+(advanced) Specifies the knn codec implementation to use
++
+
+Accepted values: `Lucene90HnswVectorsFormat`.
+
+Please note that the `codecFormat` accepted values may change in future releases.
+
+
+
+[NOTE]
+Lucene index back-compatibility is only supported for the default codec.
+If you choose to customize the `codecFormat` in your schema, upgrading to a future version of Solr may require you to either switch back to the default codec and optimize your index to rewrite it into the default codec before upgrading, or re-build your entire index from scratch after upgrading.
+
+`hnswMaxConnections`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 16
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+Controls how many of the nearest neighbor candidates are connected to the new node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `M` from the later paper.
++
+Accepted values:
+Integer.
+
+`hnswBeamWidth`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 100
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+It is the number of nearest neighbor candidates to track while searching the graph for each newly inserted node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `efConstruction` from the later paper.
++
+Accepted values:
+Integer.
+
+DenseVectorField supports the attributes: `indexed`, `stored`.
+
+*N.B.* currently multivalue is not supported
+
+Here's how a `DenseVectorField` should be indexed:
+
+[.dynamic-tabs]
+--
+[example.tab-pane#json]
+====
+[.tab-label]*JSON*
+[source,json]
+----
+[{ "id": "1",
+"vector": [1.0, 2.5, 3.7, 4.1]
+},
+{ "id": "2",
+"vector": [1.5, 5.5, 6.7, 65.1]
+}
+]
+----
+====
+
+[example.tab-pane#xml]
+====
+[.tab-label]*XML*
+[source,xml]
+----
+<add>
+<doc>
+<field name="id">1</field>
+<field name="vector">1.0</field>
+<field name="vector">2.5</field>
+<field name="vector">3.7</field>
+<field name="vector">4.1</field>
+</doc>
+<doc>
+<field name="id">2</field>
+<field name="vector">1.5</field>
+<field name="vector">5.5</field>
+<field name="vector">6.7</field>
+<field name="vector">65.1</field>
+</doc>
+</add>
+----
+====
+
+[example.tab-pane#solrj]
+====
+[.tab-label]*SolrJ*
+[source,java,indent=0]
+----
+final SolrClient client = getSolrClient();
+
+final SolrInputDocument d1 = new SolrInputDocument();
+d1.setField("id", "1");
+d1.setField("vector", Arrays.asList(1.0f, 2.5f, 3.7f, 4.1f));
+
+
+final SolrInputDocument d2 = new SolrInputDocument();
+d2.setField("id", "2");
+d2.setField("vector", Arrays.asList(1.5f, 5.5f, 6.7f, 65.1f));
+
+client.add(Arrays.asList(d1, d2));
+----
+====
+--
+
+== Query Time
+This is the list of Apache Solr query approaches designed to support Neural Search:

Review comment:
       I removed the List reference, but I would prefer to keep it as a subsection of "Query Time" to make a clear distinction.
   What do you think>

##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not be solved simply by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+
+=== DenseVectorField
+The Dense Vector field gives the possibility of indexing and searching dense vectors of float elements.
+
+e.g.
+
+`[1.0, 2.5, 3.7, 4.1]` (array of float elements)
+
+Here's how `DenseVectorField` should be configured in the schema:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`vectorDimension`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The dimension of the dense vector to pass in.
++
+Accepted values:
+Integer < = 1024.
+
+`similarityFunction`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `euclidean`
+|===
++
+Vector similarity function; used in search to return top K most similar vectors to a target vector.
++
+Accepted values: `euclidean`, `dot_product`  or `cosine`.
+
+* `euclidean`: https://en.wikipedia.org/wiki/Euclidean_distance[Euclidean distance]
+* `dot_product`: https://en.wikipedia.org/wiki/Dot_product[Dot product]. *NOTE*: this similarity is intended as an optimized way to perform cosine similarity. In order to use it, all vectors must be of unit length, including both document and query vectors. Using dot product with vectors that are not unit length can result in errors or poor search results..
+* `cosine`: https://en.wikipedia.org/wiki/Cosine_similarity[Cosine similarity]. *NOTE*: the preferred way to perform cosine similarity is to normalize all vectors to unit length, and instead use DOT_PRODUCT. You should only use this function if you need to preserve the original vectors and cannot normalize them in advance.
+
+*N.B.* To use the following advanced parameters that customise the codec format
+and the hyper-parameter of the HNSW algorithm make sure you set this configuration in the solrconfig.xml:
+[source,xml]
+<config>
+<codecFactory class="solr.SchemaCodecFactory"/>
+...
+
+Here's how `DenseVectorField` can be configured with the advanced codec hyper-parameters:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine" codecFormat="Lucene90HnswVectorsFormat" hnswMaxConnections="10" hnswBeamWidth="40"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`codecFormat`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `Lucene90HnswVectorsFormat`
+|===
++
+(advanced) Specifies the knn codec implementation to use
++
+
+Accepted values: `Lucene90HnswVectorsFormat`.
+
+Please note that the `codecFormat` accepted values may change in future releases.
+
+
+
+[NOTE]
+Lucene index back-compatibility is only supported for the default codec.
+If you choose to customize the `codecFormat` in your schema, upgrading to a future version of Solr may require you to either switch back to the default codec and optimize your index to rewrite it into the default codec before upgrading, or re-build your entire index from scratch after upgrading.
+
+`hnswMaxConnections`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 16
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+Controls how many of the nearest neighbor candidates are connected to the new node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `M` from the later paper.
++
+Accepted values:
+Integer.
+
+`hnswBeamWidth`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 100
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+It is the number of nearest neighbor candidates to track while searching the graph for each newly inserted node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `efConstruction` from the later paper.
++
+Accepted values:
+Integer.
+
+DenseVectorField supports the attributes: `indexed`, `stored`.
+
+*N.B.* currently multivalue is not supported
+
+Here's how a `DenseVectorField` should be indexed:
+
+[.dynamic-tabs]
+--
+[example.tab-pane#json]
+====
+[.tab-label]*JSON*
+[source,json]
+----
+[{ "id": "1",
+"vector": [1.0, 2.5, 3.7, 4.1]
+},
+{ "id": "2",
+"vector": [1.5, 5.5, 6.7, 65.1]
+}
+]
+----
+====
+
+[example.tab-pane#xml]
+====
+[.tab-label]*XML*
+[source,xml]
+----
+<add>
+<doc>
+<field name="id">1</field>
+<field name="vector">1.0</field>
+<field name="vector">2.5</field>
+<field name="vector">3.7</field>
+<field name="vector">4.1</field>
+</doc>
+<doc>
+<field name="id">2</field>
+<field name="vector">1.5</field>
+<field name="vector">5.5</field>
+<field name="vector">6.7</field>
+<field name="vector">65.1</field>
+</doc>
+</add>
+----
+====
+
+[example.tab-pane#solrj]
+====
+[.tab-label]*SolrJ*
+[source,java,indent=0]
+----
+final SolrClient client = getSolrClient();
+
+final SolrInputDocument d1 = new SolrInputDocument();
+d1.setField("id", "1");
+d1.setField("vector", Arrays.asList(1.0f, 2.5f, 3.7f, 4.1f));
+
+
+final SolrInputDocument d2 = new SolrInputDocument();
+d2.setField("id", "2");
+d2.setField("vector", Arrays.asList(1.5f, 5.5f, 6.7f, 65.1f));
+
+client.add(Arrays.asList(d1, d2));
+----
+====
+--
+
+== Query Time
+This is the list of Apache Solr query approaches designed to support Neural Search:

Review comment:
       I removed the List reference, but I would prefer to keep it as a subsection of "Query Time" to make a clear distinction.
   What do you think?
   




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] magibney commented on a change in pull request #476: SOLR-15880: K Nearest Neighbors Search

Posted by GitBox <gi...@apache.org>.
magibney commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r787980804



##########
File path: solr/solr-ref-guide/src/dense-vector-search.adoc
##########
@@ -0,0 +1,308 @@
+= Dense Vector Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+The Apache Solr *Dense Vector Search* module adds support for indexing and searching dense numerical vectors.
+
+https://en.wikipedia.org/wiki/Deep_learning[Deep learning] can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+These neural network-based techniques are usually referred to as neural search, an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Important Concepts
+
+=== Dense Vector Representation 
+A dense vector describes information as an array of elements, each of them explicitly defined.

Review comment:
       >each of them explicitly defined
   I'm unclear on exactly what's meant by this. In my reading, this means that the _values_ of vectors are not implicitly derived from "normal" doc or user text input (in the manner of tokenization), but are rather determined externally (e.g., by a custom model) and supplied explicitly to Solr. It's easy to interpret this statement as suggesting that the semantic significance of each dimension is explicitly defined, which iiuc is definitely _not_ the case.
   
   If I'm correctly characterizing the meaning of the above statement (and please correct me if I'm not!), I think it might be worth expanding on this a bit to explicitly clarify that in order to leverage this feature, a user _needs_ an external means of generating vectors from content. I think in context, that's probably what you're getting at by referring to "Various deep learning models..." immediately below, but I think the connection could stand to be more explicit. (incidentally, even if perhaps not worth noting in the refguide: there may well be applications -- e.g., scientific? -- for searching vector similarity that actually have nothing at all to do with language models, machine learning, etc...)




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880: K Nearest Neighbors Search

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r787689202



##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not be solved simply by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+
+=== DenseVectorField
+The Dense Vector field gives the possibility of indexing and searching dense vectors of float elements.
+
+e.g.
+
+`[1.0, 2.5, 3.7, 4.1]` (array of float elements)
+
+Here's how `DenseVectorField` should be configured in the schema:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`vectorDimension`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The dimension of the dense vector to pass in.
++
+Accepted values:
+Integer < = 1024.
+
+`similarityFunction`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `euclidean`
+|===
++
+Vector similarity function; used in search to return top K most similar vectors to a target vector.
++
+Accepted values: `euclidean`, `dot_product`  or `cosine`.
+
+* `euclidean`: https://en.wikipedia.org/wiki/Euclidean_distance[Euclidean distance]
+* `dot_product`: https://en.wikipedia.org/wiki/Dot_product[Dot product]. *NOTE*: this similarity is intended as an optimized way to perform cosine similarity. In order to use it, all vectors must be of unit length, including both document and query vectors. Using dot product with vectors that are not unit length can result in errors or poor search results..
+* `cosine`: https://en.wikipedia.org/wiki/Cosine_similarity[Cosine similarity]. *NOTE*: the preferred way to perform cosine similarity is to normalize all vectors to unit length, and instead use DOT_PRODUCT. You should only use this function if you need to preserve the original vectors and cannot normalize them in advance.
+
+*N.B.* To use the following advanced parameters that customise the codec format

Review comment:
       I think it's fine to keep it as a separate section, with all the notes.
   I gave it a try.
   Let me know if it looks better




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r776774629



##########
File path: solr/core/src/java/org/apache/solr/schema/DenseVectorField.java
##########
@@ -0,0 +1,200 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.solr.schema;
+
+import org.apache.lucene.document.KnnVectorField;
+import org.apache.lucene.document.StoredField;
+import org.apache.lucene.index.IndexableField;
+import org.apache.lucene.index.VectorSimilarityFunction;
+import org.apache.lucene.queries.function.ValueSource;
+import org.apache.lucene.search.KnnVectorQuery;
+import org.apache.lucene.search.Query;
+import org.apache.lucene.search.SortField;
+import org.apache.solr.common.SolrException;
+import org.apache.solr.response.TextResponseWriter;
+import org.apache.solr.search.QParser;
+import org.apache.solr.uninverting.UninvertingReader;
+
+import java.io.IOException;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
+
+import static java.util.Optional.ofNullable;
+
+/**
+ * Provides a field type to support Lucene's {@link
+ * org.apache.lucene.document.KnnVectorField}.
+ * See {@link org.apache.lucene.search.KnnVectorQuery} for more details.
+ * It supports a fixed cardinality dimension for the vector and a fixed similarity function.
+ * The default similarity is EUCLIDEAN_HNSW (L2).
+ * See subclasses for details.
+ *
+ * <br>
+ * Only {@code Indexed} and {@code Stored} attributes are supported.
+ */
+public class DenseVectorField extends FieldType {
+
+    static final String KNN_VECTOR_DIMENSION = "vectorDimension";
+    static final String KNN_SIMILARITY_FUNCTION = "similarityFunction";
+    
+    int dimension;
+    VectorSimilarityFunction similarityFunction;
+    VectorSimilarityFunction DEFAULT_SIMILARITY = VectorSimilarityFunction.EUCLIDEAN;
+
+    @Override
+    public void init(IndexSchema schema, Map<String, String> args){
+        this.dimension = ofNullable(args.get(KNN_VECTOR_DIMENSION))
+                .map(value -> parseDimensionParameter(value))
+                .orElseThrow(() -> new SolrException(SolrException.ErrorCode.SERVER_ERROR, "the vector dimension is a mandatory parameter"));
+        args.remove(KNN_VECTOR_DIMENSION);
+
+        this.similarityFunction = ofNullable(args.get(KNN_SIMILARITY_FUNCTION))
+                .map(value -> VectorSimilarityFunction.valueOf(value.toUpperCase(Locale.ROOT)))
+                .orElse(DEFAULT_SIMILARITY);
+        args.remove(KNN_SIMILARITY_FUNCTION);
+
+        this.properties &= ~MULTIVALUED;
+        this.properties &= ~UNINVERTIBLE;
+        
+        super.init(schema, args);
+    }
+
+    private int parseDimensionParameter(String value) {
+        try {
+            return Integer.parseInt(value);
+        } catch (NumberFormatException e) {
+            throw new SolrException(SolrException.ErrorCode.SERVER_ERROR, "the vector dimension must be an integer");
+        }
+    }
+
+    @Override
+    public void checkSchemaField(final SchemaField field) throws SolrException {
+        super.checkSchemaField(field);
+        if (field.multiValued()) {
+            throw new SolrException(SolrException.ErrorCode.SERVER_ERROR,
+                    getClass().getSimpleName() + " fields can not be multiValued: " + field.getName());
+        }
+    }
+    
+    public List<IndexableField> createFields(SchemaField field, Object value) {
+        List<IndexableField> fields = new ArrayList<>();
+        if (field.indexed()){
+            fields.add(createField(field, value));
+        }
+        if (field.stored()){
+            fields.add(createStoredField(field, value));
+        }
+        return fields;
+    }
+
+    private IndexableField createStoredField(SchemaField field, Object value) {
+        return new StoredField(field.getName(), value.toString());

Review comment:
       This should have been resolved with latest commit




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] stefan-it commented on pull request #476: SOLR-15880: K Nearest Neighbors Search

Posted by GitBox <gi...@apache.org>.
stefan-it commented on pull request #476:
URL: https://github.com/apache/solr/pull/476#issuecomment-1028873217


   Hi guys,
   
   thanks for working on this feature! I would like to index vectors with a dimension > 1024 (embeddings come from a ResNet), do you know how this would be possible :thinking: 
   
   Many thanks in advance :heart: 


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r777413036



##########
File path: solr/core/src/java/org/apache/solr/schema/DenseVectorField.java
##########
@@ -0,0 +1,211 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.solr.schema;
+
+import org.apache.lucene.document.KnnVectorField;
+import org.apache.lucene.index.IndexableField;
+import org.apache.lucene.index.VectorSimilarityFunction;
+import org.apache.lucene.queries.function.ValueSource;
+import org.apache.lucene.search.KnnVectorQuery;
+import org.apache.lucene.search.Query;
+import org.apache.lucene.search.SortField;
+import org.apache.solr.common.SolrException;
+import org.apache.solr.search.QParser;
+import org.apache.solr.uninverting.UninvertingReader;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
+
+import static java.util.Optional.ofNullable;
+
+/**
+ * Provides a field type to support Lucene's {@link
+ * org.apache.lucene.document.KnnVectorField}.
+ * See {@link org.apache.lucene.search.KnnVectorQuery} for more details.
+ * It supports a fixed cardinality dimension for the vector and a fixed similarity function.
+ * The default similarity is EUCLIDEAN_HNSW (L2).
+ * See subclasses for details.
+ *
+ * <br>
+ * Only {@code Indexed} and {@code Stored} attributes are supported.
+ */
+public class DenseVectorField extends FloatPointField {
+
+    static final String KNN_VECTOR_DIMENSION = "vectorDimension";
+    static final String KNN_SIMILARITY_FUNCTION = "similarityFunction";
+
+    int dimension;
+    VectorSimilarityFunction similarityFunction;
+    VectorSimilarityFunction DEFAULT_SIMILARITY = VectorSimilarityFunction.EUCLIDEAN;
+
+    @Override
+    public void init(IndexSchema schema, Map<String, String> args) {
+        this.dimension = ofNullable(args.get(KNN_VECTOR_DIMENSION))
+                .map(value -> parseDimensionParameter(value))
+                .orElseThrow(() -> new SolrException(SolrException.ErrorCode.SERVER_ERROR, "the vector dimension is a mandatory parameter"));
+        args.remove(KNN_VECTOR_DIMENSION);
+
+        this.similarityFunction = ofNullable(args.get(KNN_SIMILARITY_FUNCTION))
+                .map(value -> VectorSimilarityFunction.valueOf(value.toUpperCase(Locale.ROOT)))
+                .orElse(DEFAULT_SIMILARITY);
+        args.remove(KNN_SIMILARITY_FUNCTION);
+
+        this.properties &= ~MULTIVALUED;
+        this.properties &= ~UNINVERTIBLE;
+        
+        super.init(schema, args);
+    }
+
+    private int parseDimensionParameter(String value) {
+        try {
+            return Integer.parseInt(value);
+        } catch (NumberFormatException e) {
+            throw new SolrException(SolrException.ErrorCode.SERVER_ERROR, "the vector dimension must be an integer");
+        }
+    }
+
+    public int getDimension() {
+        return dimension;
+    }
+
+    @Override
+    public void checkSchemaField(final SchemaField field) throws SolrException {
+        super.checkSchemaField(field);
+        if (field.multiValued()) {
+            throw new SolrException(SolrException.ErrorCode.SERVER_ERROR,
+                    getClass().getSimpleName() + " fields can not be multiValued: " + field.getName());
+        }

Review comment:
       Hi @fmmoret , there's no ticket yet but it's in our to-do list to make an analysis of the feature, investigate the state of the art, and design and implement a solution (it may be Lucene side and Solr side, or potentially only Solr side).
   We'll publish the Pull Request soon :)




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r783020865



##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,320 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+With the *Neural Search* module Apache Solr is introducing support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not simply be solved by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+
+=== DenseVectorField
+The Dense Vector field gives the possibility of indexing and searching dense vectors of float elements.
+
+e.g.
+
+`[1.0, 2.5, 3.7, 4.1]` (array of float elements)
+
+Here's how `DenseVectorField` should be configured in the schema:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`vectorDimension`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The dimension of the dense vector to pass in.
++
+Accepted values:
+Integer < = 1024.
+
+`similarityFunction`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `euclidean`
+|===
++
+Vector similarity function; used in search to return top K most similar vectors to a target vector.
++
+Accepted values: `euclidean`, `dot_product`  or `cosine`.
+
+* `euclidean`: https://en.wikipedia.org/wiki/Euclidean_distance[Euclidean distance]
+* `dot_product`: https://en.wikipedia.org/wiki/Dot_product[Dot product]. *NOTE*: this similarity is intended as an optimized way to perform cosine similarity. In order to use it, all vectors must be of unit length, including both document and query vectors. Using dot product with vectors that are not unit length can result in errors or poor search results..
+* `cosine`: https://en.wikipedia.org/wiki/Cosine_similarity[Cosine similarity]. *NOTE*: the preferred way to perform cosine similarity is to normalize all vectors to unit length, and instead use DOT_PRODUCT. You should only use this function if you need to preserve the original vectors and cannot normalize them in advance.
+
+*N.B.* To use the following advanced parameters that customise the codec format
+and the hyper-parameter of the HNSW algorithm make sure you set this configuration in the solrconfig.xml:
+[source,xml]
+<config>
+<codecFactory class="solr.SchemaCodecFactory"/>
+...
+
+Here's how `DenseVectorField` can be configured with the advanced codec hyper-parameters:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine" codecFormat="Lucene90HnswVectorsFormat" hnswMaxConnections="10" hnswBeamWidth="40"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`codecFormat`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `Lucene90HnswVectorsFormat`
+|===
++
+(advanced) Specifies the knn codec implementation to use
++
+
+Accepted values: `Lucene90HnswVectorsFormat`.
+
+Please note that the `codecFormat` accepted values may change in future releases.
+
+
+
+[NOTE]
+Lucene index back-compatibility is only supported for the default codec.
+If you choose to customize the `codecFormat` in your schema, upgrading to a future version of Solr may require you to either switch back to the default codec and optimize your index to rewrite it into the default codec before upgrading, or re-build your entire index from scratch after upgrading.
+
+`hnswMaxConnections`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 16
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+Controls how many of the nearest neighbor candidates are connected to the new node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `M` from the later paper.
++
+Accepted values:
+Integer.
+
+`hnswBeamWidth`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 100
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+It is the number of nearest neighbor candidates to track while searching the graph for each newly inserted node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `efConstruction` from the later paper.
++
+Accepted values:
+Integer.
+
+DenseVectorField supports the attributes: `indexed`, `stored`.
+
+*N.B.* currently multivalue is not supported
+
+Here's how a `DenseVectorField` should be indexed:
+
+[.dynamic-tabs]
+--
+[example.tab-pane#json]
+====
+[.tab-label]*JSON*
+[source,json]
+----
+[{ "id": "1",
+"vector": [1.0, 2.5, 3.7, 4.1]
+},
+{ "id": "2",
+"vector": [1.5, 5.5, 6.7, 65.1]
+}
+]
+----
+====
+
+[example.tab-pane#xml]
+====
+[.tab-label]*XML*
+[source,xml]
+----
+<add>
+<doc>
+<field name="id">1</field>
+<field name="vector">1.0</field>
+<field name="vector">2.5</field>
+<field name="vector">3.7</field>
+<field name="vector">4.1</field>
+</doc>
+<doc>
+<field name="id">2</field>
+<field name="vector">1.5</field>
+<field name="vector">5.5</field>
+<field name="vector">6.7</field>
+<field name="vector">65.1</field>
+</doc>
+</add>
+----
+====
+
+[example.tab-pane#solrj]
+====
+[.tab-label]*SolrJ*
+[source,java,indent=0]
+----
+final SolrClient client = getSolrClient();
+
+final SolrInputDocument d1 = new SolrInputDocument();
+d1.setField("id", "1");
+d1.setField("vector", Arrays.asList(1.0f, 2.5f, 3.7f, 4.1f));
+
+
+final SolrInputDocument d2 = new SolrInputDocument();
+d2.setField("id", "2");
+d2.setField("vector", Arrays.asList(1.5f, 5.5f, 6.7f, 65.1f));
+
+client.add(Arrays.asList(d1, d2));
+----
+====
+--
+
+== Query Time
+This is the list of Apache Solr query approaches designed to support Neural Search:
+
+=== knn Query Parser
+The `knn` K-Nearest Neighbors query parser allows to find the k-nearest documents to the target vector according to indexed dense vectors in the given field.
+
+It takes the following parameters:
+
+`f`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The DenseVectorField to search in.
+
+`topK`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 10
+|===
++
+How many k-nearest results to return.
+
+Here's how to run a KNN search:
+
+[source,text]
+&q={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]
+
+The search results retrieved are the K-nearest to the vector in input `[1.0, 2.0, 3.0, 4.0]`, ranked by the similarityFunction configured at indexing time.
+
+==== Usage with Filter Queries
+The `knn` query parser can be used in filter queries:
+[source,text]
+&q=id:(1 2 3)&fq={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]
+
+The `knn` query parser can be used with filter queries:
+[source,text]
+&q={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]&fq=id:(1 2 3)
+
+[IMPORTANT]
+====
+When using `knn` in these scenarios make sure you have clear how filter queries work in Apache Solr:
+
+The Ranked List of document IDs resulting from the main query `q` is intersected with the set of document IDs deriving from each filter query `fq`.
+
+e.g.
+
+Ranked List from `q`=`[ID1, ID4, ID2, ID10]` <intersects> Set from `fq`=`{ID3, ID2, ID9, ID4}` = `[ID4,ID2]`
+====
+
+
+==== Usage as Re-Ranking Query
+The `knn` query parser can be used to rerank first pass query results:
+[source,text]
+&q=id:(3 4 9 2)&rq={!rerank reRankQuery=$rqq reRankDocs=4 reRankWeight=1}&rqq={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]
+
+[IMPORTANT]
+====
+When using `knn` in reranking pay attention to the `topK` parameter.
+
+The second pass score(deriving from knn) is calculated only if the documend `d` from the first pass is within
+the K-nearest neighbors(*in the whole index*) of the target vector to search.
+
+This means the second pass `knn` is executed on the whole index anyway, which is a current limitation.
+
+The final ranked list of results will have the first pass score(main query `q`) combined with the second pass score(the approximated similarityFunction distance to the target vector to search).

Review comment:
       thanks for the suggestion, fixed with the latest commit!




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r786776534



##########
File path: solr/core/src/java/org/apache/solr/schema/DenseVectorField.java
##########
@@ -0,0 +1,256 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.solr.schema;
+
+import org.apache.lucene.codecs.lucene90.Lucene90HnswVectorsFormat;
+import org.apache.lucene.document.KnnVectorField;
+import org.apache.lucene.index.IndexableField;
+import org.apache.lucene.index.VectorSimilarityFunction;
+import org.apache.lucene.queries.function.ValueSource;
+import org.apache.lucene.search.KnnVectorQuery;
+import org.apache.lucene.search.Query;
+import org.apache.lucene.search.SortField;
+import org.apache.lucene.util.hnsw.HnswGraph;
+import org.apache.solr.common.SolrException;
+import org.apache.solr.search.QParser;
+import org.apache.solr.uninverting.UninvertingReader;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
+
+import static java.util.Optional.ofNullable;
+import static org.apache.lucene.codecs.lucene90.Lucene90HnswVectorsFormat.DEFAULT_BEAM_WIDTH;
+import static org.apache.lucene.codecs.lucene90.Lucene90HnswVectorsFormat.DEFAULT_MAX_CONN;
+
+/**
+ * Provides a field type to support Lucene's {@link
+ * org.apache.lucene.document.KnnVectorField}.
+ * See {@link org.apache.lucene.search.KnnVectorQuery} for more details.
+ * It supports a fixed cardinality dimension for the vector and a fixed similarity function.
+ * The default similarity is EUCLIDEAN_HNSW (L2).
+ * The default index codec format is specified in the Lucene Codec constructor.
+ * For Lucene 9.0 e.g.
+ * See {@link org.apache.lucene.codecs.lucene90.Lucene90Codec}
+ * Currently only {@link org.apache.lucene.codecs.lucene90.Lucene90HnswVectorsFormat} is supported for
+ * advanced hyper-parameter customisation.
+ * See {@link org.apache.lucene.util.hnsw.HnswGraph} for more details about the implementation. 
+ *
+ * <br>
+ * Only {@code Indexed} and {@code Stored} attributes are supported.
+ */
+public class DenseVectorField extends FloatPointField {
+
+    static final String KNN_VECTOR_DIMENSION = "vectorDimension";
+    static final String KNN_SIMILARITY_FUNCTION = "similarityFunction";
+    
+    static final String CODEC_FORMAT = "codecFormat";
+    static final String HNSW_MAX_CONNECTIONS = "hnswMaxConnections";
+    static final String HNSW_BEAM_WIDTH = "hnswBeamWidth";
+
+    int dimension;
+    VectorSimilarityFunction similarityFunction;
+    VectorSimilarityFunction DEFAULT_SIMILARITY = VectorSimilarityFunction.EUCLIDEAN;
+
+    String codecFormat;
+    /**
+     * This parameter is coupled with the {@link Lucene90HnswVectorsFormat} format implementation.
+     * Controls how many of the nearest neighbor candidates are connected to the new node. Defaults to
+     * {@link Lucene90HnswVectorsFormat#DEFAULT_MAX_CONN}. See {@link HnswGraph} for more details.
+     */
+    int hnswMaxConn;
+    /**
+     * This parameter is coupled with the {@link Lucene90HnswVectorsFormat} format implementation.
+     * The number of candidate neighbors to track while searching the graph for each newly inserted
+     * node. Defaults to to {@link Lucene90HnswVectorsFormat#DEFAULT_BEAM_WIDTH}. See {@link
+     * HnswGraph} for details.
+     */
+    int hnswBeamWidth;
+
+    @Override
+    public void init(IndexSchema schema, Map<String, String> args) {
+        this.dimension = ofNullable(args.get(KNN_VECTOR_DIMENSION))
+                .map(value -> Integer.parseInt(value))
+                .orElseThrow(() -> new SolrException(SolrException.ErrorCode.SERVER_ERROR, "the vector dimension is a mandatory parameter"));
+        args.remove(KNN_VECTOR_DIMENSION);
+
+        this.similarityFunction = ofNullable(args.get(KNN_SIMILARITY_FUNCTION))
+                .map(value -> VectorSimilarityFunction.valueOf(value.toUpperCase(Locale.ROOT)))
+                .orElse(DEFAULT_SIMILARITY);
+        args.remove(KNN_SIMILARITY_FUNCTION);
+
+        this.codecFormat = args.get(CODEC_FORMAT);
+        args.remove(CODEC_FORMAT);
+
+        this.hnswMaxConn = ofNullable(args.get(HNSW_MAX_CONNECTIONS))
+                .map(value -> Integer.parseInt(value))
+                .orElse(DEFAULT_MAX_CONN);
+        args.remove(HNSW_MAX_CONNECTIONS);
+
+        this.hnswBeamWidth = ofNullable(args.get(HNSW_BEAM_WIDTH))
+                .map(value -> Integer.parseInt(value))
+                .orElse(DEFAULT_BEAM_WIDTH);
+        args.remove(HNSW_BEAM_WIDTH);
+
+        this.properties &= ~MULTIVALUED;
+        this.properties &= ~UNINVERTIBLE;
+        
+        super.init(schema, args);
+    }
+
+    public int getDimension() {
+        return dimension;
+    }
+
+    public String getCodecFormat() {
+        return codecFormat;
+    }
+
+    public Integer getHnswMaxConn() {
+        return hnswMaxConn;
+    }
+
+    public Integer getHnswBeamWidth() {
+        return hnswBeamWidth;
+    }
+
+    @Override
+    public void checkSchemaField(final SchemaField field) throws SolrException {
+        super.checkSchemaField(field);
+        if (field.multiValued()) {
+            throw new SolrException(SolrException.ErrorCode.SERVER_ERROR,
+                    getClass().getSimpleName() + " fields can not be multiValued: " + field.getName());
+        }
+
+        if (field.hasDocValues()) {
+            throw new SolrException(SolrException.ErrorCode.SERVER_ERROR,
+                    getClass().getSimpleName() + " fields can not have docValues: " + field.getName());
+        }
+    }
+    
+    public List<IndexableField> createFields(SchemaField field, Object value) {
+        List<IndexableField> fields = new ArrayList<>();
+        float[] parsedVector;
+        try {
+            parsedVector = parseVector(value);
+        } catch (RuntimeException e) {
+            throw new SolrException(SolrException.ErrorCode.SERVER_ERROR, "Error while creating field '" + field + "' from value '" + value + "', expected format:'[f1, f2, f3...fn]' e.g. [1.0, 3.4, 5.6]", e);
+        }
+
+        if (field.indexed()) {
+            fields.add(createField(field, parsedVector));
+        }
+        if (field.stored()) {
+            for (float vectorElement : parsedVector) {
+                fields.add(getStoredField(field, vectorElement));
+            }
+        }
+        return fields;
+    }
+
+    @Override
+    public IndexableField createField(SchemaField field, Object parsedVector) {
+        float[] typedVector;
+        if (parsedVector == null) return null;
+        typedVector = (float[]) parsedVector;
+        return new KnnVectorField(field.getName(), typedVector, similarityFunction);
+    }
+
+    /**
+     * Index Time Parsing
+     * The inputValue is an ArrayList with a type that dipends on the loader used:
+     * - {@link org.apache.solr.handler.loader.XMLLoader}, {@link org.apache.solr.handler.loader.CSVLoader} produces an ArrayList of String
+     * - {@link org.apache.solr.handler.loader.JsonLoader} produces an ArrayList of Double
+     * - {@link org.apache.solr.handler.loader.JavabinLoader} produces an ArrayList of Float
+     *
+     * @param inputValue - An {@link ArrayList} containing the elements of the vector
+     * @return the vector parsed
+     */
+    float[] parseVector(Object inputValue) {
+        if (!(inputValue instanceof List)) {
+            throw new SolrException(SolrException.ErrorCode.BAD_REQUEST, "incorrect vector format." +
+                    " The expected format is an array :'[f1,f2..f3]' where each element f is a float");
+        }
+        List<?> inputVector = (List<?>) inputValue;
+        if (inputVector.size() != dimension) {
+            throw new SolrException(SolrException.ErrorCode.BAD_REQUEST, "incorrect vector dimension." +
+                    " The vector value has size "
+                    + inputVector.size() + " while it is expected a vector with size " + dimension);
+        }
+
+        float[] vector = new float[dimension];
+        if (inputVector.get(0) instanceof CharSequence) {
+            for (int i = 0; i < dimension; i++) {
+                try {
+                    vector[i] = Float.parseFloat(inputVector.get(i).toString());
+                } catch (NumberFormatException e) {
+                    throw new SolrException(SolrException.ErrorCode.BAD_REQUEST, "incorrect vector element: '" + inputVector.get(i) +
+                            "'. The expected format is:'[f1,f2..f3]' where each element f is a float");
+                }
+            }
+        } else if (inputVector.get(0) instanceof Number) {
+            for (int i = 0; i < dimension; i++) {
+                vector[i] = ((Number) inputVector.get(i)).floatValue();
+            }
+        }
+
+        return vector;
+    }
+
+    @Override
+    public UninvertingReader.Type getUninversionType(SchemaField sf) {
+        return null;
+    }
+
+    @Override
+    public ValueSource getValueSource(SchemaField field, QParser parser) {
+        throw new SolrException(SolrException.ErrorCode.BAD_REQUEST,
+                "Function queries are not supported for Dense Vector fields.");
+    }
+
+    public Query getKnnVectorQuery(SchemaField field, float[] vectorToSearch, int topK) {
+        return new KnnVectorQuery(field.getName(), vectorToSearch, topK);
+    }
+
+    /**
+     * Not Supported

Review comment:
       can't find this one, can you elaborate it a bit?




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] joel-bernstein commented on a change in pull request #476: SOLR-15880

Posted by GitBox <gi...@apache.org>.
joel-bernstein commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r786285685



##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,322 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.

Review comment:
       I'll add a link and a section to machine-learning.adoc showing how to integrate with math expressions. This is the now the key machine learning feature in Solr and its fits quite nicely with Streaming Expressions and math expressions. I'll add the docs after the patch lands.




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880: K Nearest Neighbors Search

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r787649909



##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not be solved simply by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+
+=== DenseVectorField
+The Dense Vector field gives the possibility of indexing and searching dense vectors of float elements.
+
+e.g.
+
+`[1.0, 2.5, 3.7, 4.1]` (array of float elements)
+
+Here's how `DenseVectorField` should be configured in the schema:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`vectorDimension`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The dimension of the dense vector to pass in.
++
+Accepted values:
+Integer < = 1024.
+
+`similarityFunction`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `euclidean`
+|===
++
+Vector similarity function; used in search to return top K most similar vectors to a target vector.
++
+Accepted values: `euclidean`, `dot_product`  or `cosine`.
+
+* `euclidean`: https://en.wikipedia.org/wiki/Euclidean_distance[Euclidean distance]
+* `dot_product`: https://en.wikipedia.org/wiki/Dot_product[Dot product]. *NOTE*: this similarity is intended as an optimized way to perform cosine similarity. In order to use it, all vectors must be of unit length, including both document and query vectors. Using dot product with vectors that are not unit length can result in errors or poor search results..
+* `cosine`: https://en.wikipedia.org/wiki/Cosine_similarity[Cosine similarity]. *NOTE*: the preferred way to perform cosine similarity is to normalize all vectors to unit length, and instead use DOT_PRODUCT. You should only use this function if you need to preserve the original vectors and cannot normalize them in advance.
+
+*N.B.* To use the following advanced parameters that customise the codec format
+and the hyper-parameter of the HNSW algorithm make sure you set this configuration in the solrconfig.xml:
+[source,xml]
+<config>
+<codecFactory class="solr.SchemaCodecFactory"/>
+...
+
+Here's how `DenseVectorField` can be configured with the advanced codec hyper-parameters:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine" codecFormat="Lucene90HnswVectorsFormat" hnswMaxConnections="10" hnswBeamWidth="40"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`codecFormat`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `Lucene90HnswVectorsFormat`
+|===
++
+(advanced) Specifies the knn codec implementation to use
++
+
+Accepted values: `Lucene90HnswVectorsFormat`.
+
+Please note that the `codecFormat` accepted values may change in future releases.
+
+
+
+[NOTE]
+Lucene index back-compatibility is only supported for the default codec.
+If you choose to customize the `codecFormat` in your schema, upgrading to a future version of Solr may require you to either switch back to the default codec and optimize your index to rewrite it into the default codec before upgrading, or re-build your entire index from scratch after upgrading.
+
+`hnswMaxConnections`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 16
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+Controls how many of the nearest neighbor candidates are connected to the new node.
++

Review comment:
       Can you recommend me a rewording?
   
   In regards to the "(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
   " I would prefer to keep it:
   Potentially Lucene introduces a different format, potentially a default one, this may end up transparently in Solr in a later release given that the projects are now separated.
   With this line we make sure the user must pass the 'Lucene90HnswVectorsFormat' as a codec if he/she wants to use this advanced param.




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880: K Nearest Neighbors Search

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r787653183



##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not be solved simply by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+
+=== DenseVectorField
+The Dense Vector field gives the possibility of indexing and searching dense vectors of float elements.
+
+e.g.
+
+`[1.0, 2.5, 3.7, 4.1]` (array of float elements)
+
+Here's how `DenseVectorField` should be configured in the schema:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`vectorDimension`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The dimension of the dense vector to pass in.
++
+Accepted values:
+Integer < = 1024.
+
+`similarityFunction`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `euclidean`
+|===
++
+Vector similarity function; used in search to return top K most similar vectors to a target vector.
++
+Accepted values: `euclidean`, `dot_product`  or `cosine`.
+
+* `euclidean`: https://en.wikipedia.org/wiki/Euclidean_distance[Euclidean distance]
+* `dot_product`: https://en.wikipedia.org/wiki/Dot_product[Dot product]. *NOTE*: this similarity is intended as an optimized way to perform cosine similarity. In order to use it, all vectors must be of unit length, including both document and query vectors. Using dot product with vectors that are not unit length can result in errors or poor search results..
+* `cosine`: https://en.wikipedia.org/wiki/Cosine_similarity[Cosine similarity]. *NOTE*: the preferred way to perform cosine similarity is to normalize all vectors to unit length, and instead use DOT_PRODUCT. You should only use this function if you need to preserve the original vectors and cannot normalize them in advance.
+
+*N.B.* To use the following advanced parameters that customise the codec format
+and the hyper-parameter of the HNSW algorithm make sure you set this configuration in the solrconfig.xml:
+[source,xml]
+<config>
+<codecFactory class="solr.SchemaCodecFactory"/>
+...
+
+Here's how `DenseVectorField` can be configured with the advanced codec hyper-parameters:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine" codecFormat="Lucene90HnswVectorsFormat" hnswMaxConnections="10" hnswBeamWidth="40"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`codecFormat`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `Lucene90HnswVectorsFormat`
+|===
++
+(advanced) Specifies the knn codec implementation to use
++
+
+Accepted values: `Lucene90HnswVectorsFormat`.
+
+Please note that the `codecFormat` accepted values may change in future releases.
+
+
+
+[NOTE]
+Lucene index back-compatibility is only supported for the default codec.
+If you choose to customize the `codecFormat` in your schema, upgrading to a future version of Solr may require you to either switch back to the default codec and optimize your index to rewrite it into the default codec before upgrading, or re-build your entire index from scratch after upgrading.
+
+`hnswMaxConnections`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 16
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+Controls how many of the nearest neighbor candidates are connected to the new node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `M` from the later paper.
++
+Accepted values:
+Integer.
+
+`hnswBeamWidth`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 100

Review comment:
       Done!




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on pull request #476: SOLR-15880: K Nearest Neighbors Search

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on pull request #476:
URL: https://github.com/apache/solr/pull/476#issuecomment-1016657387


   I refactor the documentation contribution, changing the name of the section to "Dense Vector Search".
   Whenever in the future we add some additional neural search techniques, we can add a parent section that contains the various children.
   I'll wait some additional hours to gather additional feedback, especially for the documentation (thanks @ctargett again for your time).
   
   If no blockers, I'll proceed tomorrow with the merge!


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on pull request #476: SOLR-15880

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on pull request #476:
URL: https://github.com/apache/solr/pull/476#issuecomment-1009250478


   hi @msokolov ,
   I just updated the Pull Request with the support for maxConn and beamWidth customization.
   According to what Lucene currently exposes I believe it's the cleanest way to support it in Solr, but I am open to suggestions!
   Documentation has been updated accordingly.
   
   In general I'll wait for a couple of weeks to collect additional suggestions and then I'll proceed with the merge and next steps in improving Neural Search support in Apache Solr :)


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r776774765



##########
File path: solr/core/src/java/org/apache/solr/schema/DenseVectorField.java
##########
@@ -0,0 +1,200 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.solr.schema;
+
+import org.apache.lucene.document.KnnVectorField;
+import org.apache.lucene.document.StoredField;
+import org.apache.lucene.index.IndexableField;
+import org.apache.lucene.index.VectorSimilarityFunction;
+import org.apache.lucene.queries.function.ValueSource;
+import org.apache.lucene.search.KnnVectorQuery;
+import org.apache.lucene.search.Query;
+import org.apache.lucene.search.SortField;
+import org.apache.solr.common.SolrException;
+import org.apache.solr.response.TextResponseWriter;
+import org.apache.solr.search.QParser;
+import org.apache.solr.uninverting.UninvertingReader;
+
+import java.io.IOException;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
+
+import static java.util.Optional.ofNullable;
+
+/**
+ * Provides a field type to support Lucene's {@link
+ * org.apache.lucene.document.KnnVectorField}.
+ * See {@link org.apache.lucene.search.KnnVectorQuery} for more details.
+ * It supports a fixed cardinality dimension for the vector and a fixed similarity function.
+ * The default similarity is EUCLIDEAN_HNSW (L2).
+ * See subclasses for details.
+ *
+ * <br>
+ * Only {@code Indexed} and {@code Stored} attributes are supported.
+ */
+public class DenseVectorField extends FieldType {
+
+    static final String KNN_VECTOR_DIMENSION = "vectorDimension";
+    static final String KNN_SIMILARITY_FUNCTION = "similarityFunction";
+    
+    int dimension;
+    VectorSimilarityFunction similarityFunction;
+    VectorSimilarityFunction DEFAULT_SIMILARITY = VectorSimilarityFunction.EUCLIDEAN;
+
+    @Override
+    public void init(IndexSchema schema, Map<String, String> args){
+        this.dimension = ofNullable(args.get(KNN_VECTOR_DIMENSION))
+                .map(value -> parseDimensionParameter(value))
+                .orElseThrow(() -> new SolrException(SolrException.ErrorCode.SERVER_ERROR, "the vector dimension is a mandatory parameter"));
+        args.remove(KNN_VECTOR_DIMENSION);
+
+        this.similarityFunction = ofNullable(args.get(KNN_SIMILARITY_FUNCTION))
+                .map(value -> VectorSimilarityFunction.valueOf(value.toUpperCase(Locale.ROOT)))
+                .orElse(DEFAULT_SIMILARITY);
+        args.remove(KNN_SIMILARITY_FUNCTION);
+
+        this.properties &= ~MULTIVALUED;
+        this.properties &= ~UNINVERTIBLE;
+        
+        super.init(schema, args);
+    }
+
+    private int parseDimensionParameter(String value) {
+        try {
+            return Integer.parseInt(value);
+        } catch (NumberFormatException e) {
+            throw new SolrException(SolrException.ErrorCode.SERVER_ERROR, "the vector dimension must be an integer");
+        }
+    }
+
+    @Override
+    public void checkSchemaField(final SchemaField field) throws SolrException {
+        super.checkSchemaField(field);
+        if (field.multiValued()) {
+            throw new SolrException(SolrException.ErrorCode.SERVER_ERROR,
+                    getClass().getSimpleName() + " fields can not be multiValued: " + field.getName());
+        }
+    }
+    
+    public List<IndexableField> createFields(SchemaField field, Object value) {
+        List<IndexableField> fields = new ArrayList<>();
+        if (field.indexed()){
+            fields.add(createField(field, value));
+        }
+        if (field.stored()){
+            fields.add(createStoredField(field, value));
+        }
+        return fields;
+    }
+
+    private IndexableField createStoredField(SchemaField field, Object value) {
+        return new StoredField(field.getName(), value.toString());
+    }
+
+    @Override
+    public UninvertingReader.Type getUninversionType(SchemaField sf) {
+        return null;
+    }
+
+    @Override
+    public ValueSource getValueSource(SchemaField field, QParser parser) {
+        throw new SolrException(SolrException.ErrorCode.BAD_REQUEST,
+                "Function queries are not supported for Dense Vector fields.");
+    }
+
+    @Override
+    public void write(TextResponseWriter writer, String name, IndexableField f) throws IOException {
+        writer.writeVal(name, f.stringValue());
+    }
+
+    @Override
+    public IndexableField createField(SchemaField field, Object value) {
+        float[] parsedVector;
+        try {
+            parsedVector = parseVector(value.toString());
+        } catch (RuntimeException e) {
+            throw new SolrException(SolrException.ErrorCode.SERVER_ERROR, "Error while creating field '" + field + "' from value '" + value + "', expected format:'[f1, f2, f3...fn]' e.g. [1.0, 3.4, 5.6]", e);
+        }
+        if (parsedVector == null) return null;
+
+        return new KnnVectorField(field.getName(), parsedVector, similarityFunction);
+    }
+
+    /**
+     * Parses a String vector.
+     *
+     * @param value with format: [f1, f2, f3, f4...fn]

Review comment:
       This should have been resolved with latest commit




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r786791679



##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,322 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not be solved simply by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+
+=== DenseVectorField
+The Dense Vector field gives the possibility of indexing and searching dense vectors of float elements.
+
+e.g.
+
+`[1.0, 2.5, 3.7, 4.1]` (array of float elements)
+
+Here's how `DenseVectorField` should be configured in the schema:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`vectorDimension`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The dimension of the dense vector to pass in.
++
+Accepted values:
+Integer < = 1024.
+
+`similarityFunction`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `euclidean`
+|===
++
+Vector similarity function; used in search to return top K most similar vectors to a target vector.
++
+Accepted values: `euclidean`, `dot_product`  or `cosine`.
+
+* `euclidean`: https://en.wikipedia.org/wiki/Euclidean_distance[Euclidean distance]
+* `dot_product`: https://en.wikipedia.org/wiki/Dot_product[Dot product]. *NOTE*: this similarity is intended as an optimized way to perform cosine similarity. In order to use it, all vectors must be of unit length, including both document and query vectors. Using dot product with vectors that are not unit length can result in errors or poor search results..
+* `cosine`: https://en.wikipedia.org/wiki/Cosine_similarity[Cosine similarity]. *NOTE*: the preferred way to perform cosine similarity is to normalize all vectors to unit length, and instead use DOT_PRODUCT. You should only use this function if you need to preserve the original vectors and cannot normalize them in advance.
+
+*N.B.* To use the following advanced parameters that customise the codec format
+and the hyper-parameter of the HNSW algorithm make sure you set this configuration in the solrconfig.xml:
+[source,xml]
+<config>
+<codecFactory class="solr.SchemaCodecFactory"/>
+...
+
+Here's how `DenseVectorField` can be configured with the advanced codec hyper-parameters:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine" codecFormat="Lucene90HnswVectorsFormat" hnswMaxConnections="10" hnswBeamWidth="40"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`codecFormat`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `Lucene90HnswVectorsFormat`
+|===
++
+(advanced) Specifies the knn codec implementation to use
++
+
+Accepted values: `Lucene90HnswVectorsFormat`.
+
+Please note that the `codecFormat` accepted values may change in future releases.
+
+
+
+[NOTE]
+Lucene index back-compatibility is only supported for the default codec.
+If you choose to customize the `codecFormat` in your schema, upgrading to a future version of Solr may require you to either switch back to the default codec and optimize your index to rewrite it into the default codec before upgrading, or re-build your entire index from scratch after upgrading.
+
+`hnswMaxConnections`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 16
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+Controls how many of the nearest neighbor candidates are connected to the new node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `M` from the later paper.
++
+Accepted values:
+Integer.
+
+`hnswBeamWidth`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 100
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+It is the number of nearest neighbor candidates to track while searching the graph for each newly inserted node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `efConstruction` from the later paper.
++
+Accepted values:
+Integer.
+
+DenseVectorField supports the attributes: `indexed`, `stored`.
+
+*N.B.* currently multivalue is not supported
+
+Here's how a `DenseVectorField` should be indexed:
+
+[.dynamic-tabs]
+--
+[example.tab-pane#json]
+====
+[.tab-label]*JSON*
+[source,json]
+----
+[{ "id": "1",
+"vector": [1.0, 2.5, 3.7, 4.1]
+},
+{ "id": "2",
+"vector": [1.5, 5.5, 6.7, 65.1]
+}
+]
+----
+====
+
+[example.tab-pane#xml]
+====
+[.tab-label]*XML*
+[source,xml]
+----
+<add>
+<doc>
+<field name="id">1</field>
+<field name="vector">1.0</field>
+<field name="vector">2.5</field>
+<field name="vector">3.7</field>
+<field name="vector">4.1</field>
+</doc>
+<doc>
+<field name="id">2</field>
+<field name="vector">1.5</field>
+<field name="vector">5.5</field>
+<field name="vector">6.7</field>
+<field name="vector">65.1</field>
+</doc>
+</add>
+----
+====
+
+[example.tab-pane#solrj]
+====
+[.tab-label]*SolrJ*
+[source,java,indent=0]
+----
+final SolrClient client = getSolrClient();
+
+final SolrInputDocument d1 = new SolrInputDocument();
+d1.setField("id", "1");
+d1.setField("vector", Arrays.asList(1.0f, 2.5f, 3.7f, 4.1f));
+
+
+final SolrInputDocument d2 = new SolrInputDocument();
+d2.setField("id", "2");
+d2.setField("vector", Arrays.asList(1.5f, 5.5f, 6.7f, 65.1f));
+
+client.add(Arrays.asList(d1, d2));
+----
+====
+--
+
+== Query Time
+This is the list of Apache Solr query approaches designed to support Neural Search:
+
+=== knn Query Parser
+The `knn` K-Nearest Neighbors query parser allows to find the k-nearest documents to the target vector according to indexed dense vectors in the given field.
+
+It takes the following parameters:
+
+`f`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The DenseVectorField to search in.
+
+`topK`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 10
+|===
++
+How many k-nearest results to return.
+
+Here's how to run a KNN search:
+
+[source,text]
+&q={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]
+
+The search results retrieved are the K-nearest to the vector in input `[1.0, 2.0, 3.0, 4.0]`, ranked by the similarityFunction configured at indexing time.
+
+==== Usage with Filter Queries
+The `knn` query parser can be used in filter queries:
+[source,text]
+&q=id:(1 2 3)&fq={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]
+
+The `knn` query parser can be used with filter queries:
+[source,text]
+&q={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]&fq=id:(1 2 3)
+
+[IMPORTANT]
+====
+When using `knn` in these scenarios make sure you have a clear understanding of how filter queries work in Apache Solr:
+
+The Ranked List of document IDs resulting from the main query `q` is intersected with the set of document IDs deriving from each filter query `fq`.
+
+e.g.
+
+Ranked List from `q`=`[ID1, ID4, ID2, ID10]` <intersects> Set from `fq`=`{ID3, ID2, ID9, ID4}` = `[ID4,ID2]`
+====
+
+
+==== Usage as Re-Ranking Query
+The `knn` query parser can be used to rerank first pass query results:
+[source,text]
+&q=id:(3 4 9 2)&rq={!rerank reRankQuery=$rqq reRankDocs=4 reRankWeight=1}&rqq={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]
+
+[IMPORTANT]
+====
+When using `knn` in reranking pay attention to the `topK` parameter.
+
+The second pass score(deriving from knn) is calculated only if the document `d` from the first pass is within
+the K-nearest neighbors(*in the whole index*) of the target vector to search.
+
+This means the second pass `knn` is executed on the whole index anyway, which is a current limitation.
+
+The final ranked list of results will have the first pass score(main query `q`) added to the second pass score(the approximated similarityFunction distance to the target vector to search) multiplied by a multiplicative factor(reRankWeight).
+
+Details about using the ReRank Query Parser can be found in the <<query-re-ranking.adoc#,Query Re-Ranking>> section.

Review comment:
       mmm on this one, let's wait a bit because at this current stage I wouldn't recommend using it with the reranking unless you are really ok with the current behavior.
   
   There's in my TO DO list a new reranker to design and develop that should become the "GO TO" for neural reranking, I'll add that to the reranker doc when ready!




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] ctargett commented on a change in pull request #476: SOLR-15880: K Nearest Neighbors Search

Posted by GitBox <gi...@apache.org>.
ctargett commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r787180726



##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not be solved simply by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+

Review comment:
       "Deep Learning" - both words are always capitalized? But "vector" in the previous sentence wasn't?
   
   Also "Dense Retrieval" needs to be capitalized?
   
   It seems we're just capitalizing "Dense" and maybe or maybe not the word next to it. 
   
   Skimming the literature, it seems "dense" is perfectly acceptable, and if it doesn't need to be capitalized the other words don't need to be either.

##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+

Review comment:
       L#36-40 seem totally tangential to the topic at hand.

##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not be solved simply by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+

Review comment:
       "Dense vector" - vector should not be capitalized?

##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+

Review comment:
       Prefer "neural network-based techniques"
   
   Which ones? It's not all the ones a reader might be thinking of, right?
   
   Also I'd start the page with this and drop the preceding list.

##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+

Review comment:
       This feels somewhat unnecessary, particularly as the very first thing we say about this feature on the page. We're not introducing a reader to search in general - there are other sections of the Ref Guide for that, and we can assume if they are IN the Ref Guide, they know a spot or two about search.

##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not be solved simply by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+

Review comment:
       Here's an example where we're no longer capitalizing "dense"...let's be consistent.
   
   Also, should there be a space between "distance" and the open parens "("?

##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not be solved simply by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+
+=== DenseVectorField
+The Dense Vector field gives the possibility of indexing and searching dense vectors of float elements.
+
+e.g.
+
+`[1.0, 2.5, 3.7, 4.1]` (array of float elements)
+
+Here's how `DenseVectorField` should be configured in the schema:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`vectorDimension`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++

Review comment:
       The structure for this is always to include the default cell even if there is no default ("Default: none", and the word "Mandatory" should be "Required" in bold. See cluster-plugins.adoc for an example:
   
   ```
   [%autowidth,frame=none]
   |===
   s|Required |Default: none
   |===
   ```

##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not be solved simply by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+
+=== DenseVectorField
+The Dense Vector field gives the possibility of indexing and searching dense vectors of float elements.
+
+e.g.
+
+`[1.0, 2.5, 3.7, 4.1]` (array of float elements)
+
+Here's how `DenseVectorField` should be configured in the schema:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`vectorDimension`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The dimension of the dense vector to pass in.
++
+Accepted values:
+Integer < = 1024.
+
+`similarityFunction`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `euclidean`
+|===
++
+Vector similarity function; used in search to return top K most similar vectors to a target vector.
++
+Accepted values: `euclidean`, `dot_product`  or `cosine`.
+
+* `euclidean`: https://en.wikipedia.org/wiki/Euclidean_distance[Euclidean distance]
+* `dot_product`: https://en.wikipedia.org/wiki/Dot_product[Dot product]. *NOTE*: this similarity is intended as an optimized way to perform cosine similarity. In order to use it, all vectors must be of unit length, including both document and query vectors. Using dot product with vectors that are not unit length can result in errors or poor search results..
+* `cosine`: https://en.wikipedia.org/wiki/Cosine_similarity[Cosine similarity]. *NOTE*: the preferred way to perform cosine similarity is to normalize all vectors to unit length, and instead use DOT_PRODUCT. You should only use this function if you need to preserve the original vectors and cannot normalize them in advance.
+
+*N.B.* To use the following advanced parameters that customise the codec format

Review comment:
       This section should be part of the previous parameters? If so, it is not rendering that way. To get it to be with the previous section you need to add a line with only a `+` on it.
   
   Is this supposed to be a tip or note? Why not use the asciidoctor note syntax? (`NOTE::` or `[NOTE]` if it is longer than 1 line.)

##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not be solved simply by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+
+=== DenseVectorField
+The Dense Vector field gives the possibility of indexing and searching dense vectors of float elements.
+
+e.g.
+
+`[1.0, 2.5, 3.7, 4.1]` (array of float elements)
+
+Here's how `DenseVectorField` should be configured in the schema:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`vectorDimension`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The dimension of the dense vector to pass in.
++
+Accepted values:
+Integer < = 1024.
+
+`similarityFunction`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `euclidean`
+|===
++
+Vector similarity function; used in search to return top K most similar vectors to a target vector.
++
+Accepted values: `euclidean`, `dot_product`  or `cosine`.
+
+* `euclidean`: https://en.wikipedia.org/wiki/Euclidean_distance[Euclidean distance]
+* `dot_product`: https://en.wikipedia.org/wiki/Dot_product[Dot product]. *NOTE*: this similarity is intended as an optimized way to perform cosine similarity. In order to use it, all vectors must be of unit length, including both document and query vectors. Using dot product with vectors that are not unit length can result in errors or poor search results..
+* `cosine`: https://en.wikipedia.org/wiki/Cosine_similarity[Cosine similarity]. *NOTE*: the preferred way to perform cosine similarity is to normalize all vectors to unit length, and instead use DOT_PRODUCT. You should only use this function if you need to preserve the original vectors and cannot normalize them in advance.
+
+*N.B.* To use the following advanced parameters that customise the codec format
+and the hyper-parameter of the HNSW algorithm make sure you set this configuration in the solrconfig.xml:

Review comment:
       `solrconfig.xml` should be in monospace here. 
   
   Also in English "the" in front of it is a bit awkward so could be dropped.

##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not be solved simply by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+
+=== DenseVectorField
+The Dense Vector field gives the possibility of indexing and searching dense vectors of float elements.
+
+e.g.
+
+`[1.0, 2.5, 3.7, 4.1]` (array of float elements)
+
+Here's how `DenseVectorField` should be configured in the schema:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`vectorDimension`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The dimension of the dense vector to pass in.
++
+Accepted values:
+Integer < = 1024.
+
+`similarityFunction`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `euclidean`
+|===
++
+Vector similarity function; used in search to return top K most similar vectors to a target vector.
++
+Accepted values: `euclidean`, `dot_product`  or `cosine`.
+
+* `euclidean`: https://en.wikipedia.org/wiki/Euclidean_distance[Euclidean distance]
+* `dot_product`: https://en.wikipedia.org/wiki/Dot_product[Dot product]. *NOTE*: this similarity is intended as an optimized way to perform cosine similarity. In order to use it, all vectors must be of unit length, including both document and query vectors. Using dot product with vectors that are not unit length can result in errors or poor search results..
+* `cosine`: https://en.wikipedia.org/wiki/Cosine_similarity[Cosine similarity]. *NOTE*: the preferred way to perform cosine similarity is to normalize all vectors to unit length, and instead use DOT_PRODUCT. You should only use this function if you need to preserve the original vectors and cannot normalize them in advance.
+
+*N.B.* To use the following advanced parameters that customise the codec format
+and the hyper-parameter of the HNSW algorithm make sure you set this configuration in the solrconfig.xml:
+[source,xml]
+<config>
+<codecFactory class="solr.SchemaCodecFactory"/>
+...
+
+Here's how `DenseVectorField` can be configured with the advanced codec hyper-parameters:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine" codecFormat="Lucene90HnswVectorsFormat" hnswMaxConnections="10" hnswBeamWidth="40"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`codecFormat`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `Lucene90HnswVectorsFormat`
+|===
++
+(advanced) Specifies the knn codec implementation to use
++
+
+Accepted values: `Lucene90HnswVectorsFormat`.
+
+Please note that the `codecFormat` accepted values may change in future releases.
+
+
+
+[NOTE]
+Lucene index back-compatibility is only supported for the default codec.
+If you choose to customize the `codecFormat` in your schema, upgrading to a future version of Solr may require you to either switch back to the default codec and optimize your index to rewrite it into the default codec before upgrading, or re-build your entire index from scratch after upgrading.
+
+`hnswMaxConnections`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 16
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+Controls how many of the nearest neighbor candidates are connected to the new node.
++

Review comment:
       This can be reworded a little bit. I think it could be a single sentence. Of course it's valid only for the only supported codec format, so that doesn't really need to be emphasized until a different format is supported.

##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not be solved simply by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+
+=== DenseVectorField
+The Dense Vector field gives the possibility of indexing and searching dense vectors of float elements.
+
+e.g.
+
+`[1.0, 2.5, 3.7, 4.1]` (array of float elements)
+
+Here's how `DenseVectorField` should be configured in the schema:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`vectorDimension`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The dimension of the dense vector to pass in.
++
+Accepted values:
+Integer < = 1024.
+
+`similarityFunction`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `euclidean`
+|===
++
+Vector similarity function; used in search to return top K most similar vectors to a target vector.
++
+Accepted values: `euclidean`, `dot_product`  or `cosine`.
+
+* `euclidean`: https://en.wikipedia.org/wiki/Euclidean_distance[Euclidean distance]
+* `dot_product`: https://en.wikipedia.org/wiki/Dot_product[Dot product]. *NOTE*: this similarity is intended as an optimized way to perform cosine similarity. In order to use it, all vectors must be of unit length, including both document and query vectors. Using dot product with vectors that are not unit length can result in errors or poor search results..
+* `cosine`: https://en.wikipedia.org/wiki/Cosine_similarity[Cosine similarity]. *NOTE*: the preferred way to perform cosine similarity is to normalize all vectors to unit length, and instead use DOT_PRODUCT. You should only use this function if you need to preserve the original vectors and cannot normalize them in advance.
+
+*N.B.* To use the following advanced parameters that customise the codec format
+and the hyper-parameter of the HNSW algorithm make sure you set this configuration in the solrconfig.xml:
+[source,xml]
+<config>
+<codecFactory class="solr.SchemaCodecFactory"/>
+...
+
+Here's how `DenseVectorField` can be configured with the advanced codec hyper-parameters:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine" codecFormat="Lucene90HnswVectorsFormat" hnswMaxConnections="10" hnswBeamWidth="40"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`codecFormat`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `Lucene90HnswVectorsFormat`
+|===
++
+(advanced) Specifies the knn codec implementation to use
++
+
+Accepted values: `Lucene90HnswVectorsFormat`.
+
+Please note that the `codecFormat` accepted values may change in future releases.
+
+
+
+[NOTE]
+Lucene index back-compatibility is only supported for the default codec.
+If you choose to customize the `codecFormat` in your schema, upgrading to a future version of Solr may require you to either switch back to the default codec and optimize your index to rewrite it into the default codec before upgrading, or re-build your entire index from scratch after upgrading.
+
+`hnswMaxConnections`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 16

Review comment:
       All example parameter values should be in monospace, so "`16`".

##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not be solved simply by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+
+=== DenseVectorField
+The Dense Vector field gives the possibility of indexing and searching dense vectors of float elements.
+
+e.g.
+
+`[1.0, 2.5, 3.7, 4.1]` (array of float elements)
+
+Here's how `DenseVectorField` should be configured in the schema:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`vectorDimension`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The dimension of the dense vector to pass in.
++
+Accepted values:
+Integer < = 1024.
+
+`similarityFunction`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `euclidean`
+|===
++
+Vector similarity function; used in search to return top K most similar vectors to a target vector.
++
+Accepted values: `euclidean`, `dot_product`  or `cosine`.
+
+* `euclidean`: https://en.wikipedia.org/wiki/Euclidean_distance[Euclidean distance]
+* `dot_product`: https://en.wikipedia.org/wiki/Dot_product[Dot product]. *NOTE*: this similarity is intended as an optimized way to perform cosine similarity. In order to use it, all vectors must be of unit length, including both document and query vectors. Using dot product with vectors that are not unit length can result in errors or poor search results..
+* `cosine`: https://en.wikipedia.org/wiki/Cosine_similarity[Cosine similarity]. *NOTE*: the preferred way to perform cosine similarity is to normalize all vectors to unit length, and instead use DOT_PRODUCT. You should only use this function if you need to preserve the original vectors and cannot normalize them in advance.
+
+*N.B.* To use the following advanced parameters that customise the codec format
+and the hyper-parameter of the HNSW algorithm make sure you set this configuration in the solrconfig.xml:
+[source,xml]
+<config>
+<codecFactory class="solr.SchemaCodecFactory"/>
+...
+
+Here's how `DenseVectorField` can be configured with the advanced codec hyper-parameters:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine" codecFormat="Lucene90HnswVectorsFormat" hnswMaxConnections="10" hnswBeamWidth="40"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`codecFormat`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `Lucene90HnswVectorsFormat`
+|===
++
+(advanced) Specifies the knn codec implementation to use
++
+
+Accepted values: `Lucene90HnswVectorsFormat`.
+
+Please note that the `codecFormat` accepted values may change in future releases.
+
+
+
+[NOTE]
+Lucene index back-compatibility is only supported for the default codec.
+If you choose to customize the `codecFormat` in your schema, upgrading to a future version of Solr may require you to either switch back to the default codec and optimize your index to rewrite it into the default codec before upgrading, or re-build your entire index from scratch after upgrading.
+
+`hnswMaxConnections`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 16
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+Controls how many of the nearest neighbor candidates are connected to the new node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `M` from the later paper.
++
+Accepted values:
+Integer.

Review comment:
       This is an integer? Perhaps say "Any integer" instead.

##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not be solved simply by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+
+=== DenseVectorField
+The Dense Vector field gives the possibility of indexing and searching dense vectors of float elements.
+
+e.g.
+
+`[1.0, 2.5, 3.7, 4.1]` (array of float elements)
+
+Here's how `DenseVectorField` should be configured in the schema:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`vectorDimension`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The dimension of the dense vector to pass in.
++
+Accepted values:
+Integer < = 1024.
+
+`similarityFunction`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `euclidean`
+|===
++
+Vector similarity function; used in search to return top K most similar vectors to a target vector.
++
+Accepted values: `euclidean`, `dot_product`  or `cosine`.
+
+* `euclidean`: https://en.wikipedia.org/wiki/Euclidean_distance[Euclidean distance]
+* `dot_product`: https://en.wikipedia.org/wiki/Dot_product[Dot product]. *NOTE*: this similarity is intended as an optimized way to perform cosine similarity. In order to use it, all vectors must be of unit length, including both document and query vectors. Using dot product with vectors that are not unit length can result in errors or poor search results..
+* `cosine`: https://en.wikipedia.org/wiki/Cosine_similarity[Cosine similarity]. *NOTE*: the preferred way to perform cosine similarity is to normalize all vectors to unit length, and instead use DOT_PRODUCT. You should only use this function if you need to preserve the original vectors and cannot normalize them in advance.
+
+*N.B.* To use the following advanced parameters that customise the codec format
+and the hyper-parameter of the HNSW algorithm make sure you set this configuration in the solrconfig.xml:
+[source,xml]
+<config>
+<codecFactory class="solr.SchemaCodecFactory"/>
+...
+
+Here's how `DenseVectorField` can be configured with the advanced codec hyper-parameters:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine" codecFormat="Lucene90HnswVectorsFormat" hnswMaxConnections="10" hnswBeamWidth="40"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`codecFormat`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `Lucene90HnswVectorsFormat`
+|===
++
+(advanced) Specifies the knn codec implementation to use
++
+
+Accepted values: `Lucene90HnswVectorsFormat`.
+
+Please note that the `codecFormat` accepted values may change in future releases.
+
+
+
+[NOTE]
+Lucene index back-compatibility is only supported for the default codec.
+If you choose to customize the `codecFormat` in your schema, upgrading to a future version of Solr may require you to either switch back to the default codec and optimize your index to rewrite it into the default codec before upgrading, or re-build your entire index from scratch after upgrading.
+
+`hnswMaxConnections`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 16
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+Controls how many of the nearest neighbor candidates are connected to the new node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `M` from the later paper.
++
+Accepted values:
+Integer.
+
+`hnswBeamWidth`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 100

Review comment:
       See above - all parameter values should be in monospace.

##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not be solved simply by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+
+=== DenseVectorField
+The Dense Vector field gives the possibility of indexing and searching dense vectors of float elements.
+
+e.g.
+
+`[1.0, 2.5, 3.7, 4.1]` (array of float elements)
+
+Here's how `DenseVectorField` should be configured in the schema:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`vectorDimension`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The dimension of the dense vector to pass in.
++
+Accepted values:
+Integer < = 1024.
+
+`similarityFunction`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `euclidean`
+|===
++
+Vector similarity function; used in search to return top K most similar vectors to a target vector.
++
+Accepted values: `euclidean`, `dot_product`  or `cosine`.
+
+* `euclidean`: https://en.wikipedia.org/wiki/Euclidean_distance[Euclidean distance]
+* `dot_product`: https://en.wikipedia.org/wiki/Dot_product[Dot product]. *NOTE*: this similarity is intended as an optimized way to perform cosine similarity. In order to use it, all vectors must be of unit length, including both document and query vectors. Using dot product with vectors that are not unit length can result in errors or poor search results..
+* `cosine`: https://en.wikipedia.org/wiki/Cosine_similarity[Cosine similarity]. *NOTE*: the preferred way to perform cosine similarity is to normalize all vectors to unit length, and instead use DOT_PRODUCT. You should only use this function if you need to preserve the original vectors and cannot normalize them in advance.
+
+*N.B.* To use the following advanced parameters that customise the codec format
+and the hyper-parameter of the HNSW algorithm make sure you set this configuration in the solrconfig.xml:
+[source,xml]
+<config>
+<codecFactory class="solr.SchemaCodecFactory"/>
+...
+
+Here's how `DenseVectorField` can be configured with the advanced codec hyper-parameters:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine" codecFormat="Lucene90HnswVectorsFormat" hnswMaxConnections="10" hnswBeamWidth="40"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`codecFormat`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `Lucene90HnswVectorsFormat`
+|===
++
+(advanced) Specifies the knn codec implementation to use
++
+
+Accepted values: `Lucene90HnswVectorsFormat`.
+
+Please note that the `codecFormat` accepted values may change in future releases.
+
+
+
+[NOTE]
+Lucene index back-compatibility is only supported for the default codec.
+If you choose to customize the `codecFormat` in your schema, upgrading to a future version of Solr may require you to either switch back to the default codec and optimize your index to rewrite it into the default codec before upgrading, or re-build your entire index from scratch after upgrading.
+
+`hnswMaxConnections`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 16
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+Controls how many of the nearest neighbor candidates are connected to the new node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `M` from the later paper.
++
+Accepted values:
+Integer.
+
+`hnswBeamWidth`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 100
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+It is the number of nearest neighbor candidates to track while searching the graph for each newly inserted node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `efConstruction` from the later paper.
++
+Accepted values:
+Integer.
+
+DenseVectorField supports the attributes: `indexed`, `stored`.

Review comment:
       This is monospace only 2 lines later and at several points earlier, so should be monospace here.

##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not be solved simply by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+
+=== DenseVectorField
+The Dense Vector field gives the possibility of indexing and searching dense vectors of float elements.
+
+e.g.
+
+`[1.0, 2.5, 3.7, 4.1]` (array of float elements)
+
+Here's how `DenseVectorField` should be configured in the schema:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`vectorDimension`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The dimension of the dense vector to pass in.
++
+Accepted values:
+Integer < = 1024.
+
+`similarityFunction`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `euclidean`
+|===
++
+Vector similarity function; used in search to return top K most similar vectors to a target vector.
++
+Accepted values: `euclidean`, `dot_product`  or `cosine`.
+
+* `euclidean`: https://en.wikipedia.org/wiki/Euclidean_distance[Euclidean distance]
+* `dot_product`: https://en.wikipedia.org/wiki/Dot_product[Dot product]. *NOTE*: this similarity is intended as an optimized way to perform cosine similarity. In order to use it, all vectors must be of unit length, including both document and query vectors. Using dot product with vectors that are not unit length can result in errors or poor search results..
+* `cosine`: https://en.wikipedia.org/wiki/Cosine_similarity[Cosine similarity]. *NOTE*: the preferred way to perform cosine similarity is to normalize all vectors to unit length, and instead use DOT_PRODUCT. You should only use this function if you need to preserve the original vectors and cannot normalize them in advance.
+
+*N.B.* To use the following advanced parameters that customise the codec format
+and the hyper-parameter of the HNSW algorithm make sure you set this configuration in the solrconfig.xml:
+[source,xml]
+<config>
+<codecFactory class="solr.SchemaCodecFactory"/>
+...
+
+Here's how `DenseVectorField` can be configured with the advanced codec hyper-parameters:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine" codecFormat="Lucene90HnswVectorsFormat" hnswMaxConnections="10" hnswBeamWidth="40"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`codecFormat`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `Lucene90HnswVectorsFormat`
+|===
++
+(advanced) Specifies the knn codec implementation to use
++
+
+Accepted values: `Lucene90HnswVectorsFormat`.
+
+Please note that the `codecFormat` accepted values may change in future releases.
+
+
+
+[NOTE]
+Lucene index back-compatibility is only supported for the default codec.
+If you choose to customize the `codecFormat` in your schema, upgrading to a future version of Solr may require you to either switch back to the default codec and optimize your index to rewrite it into the default codec before upgrading, or re-build your entire index from scratch after upgrading.
+
+`hnswMaxConnections`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 16
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+Controls how many of the nearest neighbor candidates are connected to the new node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `M` from the later paper.
++
+Accepted values:
+Integer.
+
+`hnswBeamWidth`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 100
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+It is the number of nearest neighbor candidates to track while searching the graph for each newly inserted node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `efConstruction` from the later paper.
++
+Accepted values:
+Integer.
+
+DenseVectorField supports the attributes: `indexed`, `stored`.
+
+*N.B.* currently multivalue is not supported
+
+Here's how a `DenseVectorField` should be indexed:
+
+[.dynamic-tabs]
+--
+[example.tab-pane#json]
+====
+[.tab-label]*JSON*
+[source,json]
+----
+[{ "id": "1",
+"vector": [1.0, 2.5, 3.7, 4.1]
+},
+{ "id": "2",
+"vector": [1.5, 5.5, 6.7, 65.1]
+}
+]
+----
+====
+
+[example.tab-pane#xml]
+====
+[.tab-label]*XML*
+[source,xml]
+----
+<add>
+<doc>
+<field name="id">1</field>
+<field name="vector">1.0</field>
+<field name="vector">2.5</field>
+<field name="vector">3.7</field>
+<field name="vector">4.1</field>
+</doc>
+<doc>
+<field name="id">2</field>
+<field name="vector">1.5</field>
+<field name="vector">5.5</field>
+<field name="vector">6.7</field>
+<field name="vector">65.1</field>
+</doc>
+</add>
+----
+====
+
+[example.tab-pane#solrj]
+====
+[.tab-label]*SolrJ*
+[source,java,indent=0]
+----
+final SolrClient client = getSolrClient();
+
+final SolrInputDocument d1 = new SolrInputDocument();
+d1.setField("id", "1");
+d1.setField("vector", Arrays.asList(1.0f, 2.5f, 3.7f, 4.1f));
+
+
+final SolrInputDocument d2 = new SolrInputDocument();
+d2.setField("id", "2");
+d2.setField("vector", Arrays.asList(1.5f, 5.5f, 6.7f, 65.1f));
+
+client.add(Arrays.asList(d1, d2));
+----
+====
+--
+
+== Query Time
+This is the list of Apache Solr query approaches designed to support Neural Search:

Review comment:
       Same two comments as earlier. This says it's a list, but it's just one item. And since it's one item the subsection could be collapsed to just be the title of the section "KNN Query Parser"

##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not be solved simply by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+
+=== DenseVectorField
+The Dense Vector field gives the possibility of indexing and searching dense vectors of float elements.
+
+e.g.
+
+`[1.0, 2.5, 3.7, 4.1]` (array of float elements)
+
+Here's how `DenseVectorField` should be configured in the schema:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`vectorDimension`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The dimension of the dense vector to pass in.
++
+Accepted values:
+Integer < = 1024.
+
+`similarityFunction`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `euclidean`
+|===
++
+Vector similarity function; used in search to return top K most similar vectors to a target vector.
++
+Accepted values: `euclidean`, `dot_product`  or `cosine`.
+
+* `euclidean`: https://en.wikipedia.org/wiki/Euclidean_distance[Euclidean distance]
+* `dot_product`: https://en.wikipedia.org/wiki/Dot_product[Dot product]. *NOTE*: this similarity is intended as an optimized way to perform cosine similarity. In order to use it, all vectors must be of unit length, including both document and query vectors. Using dot product with vectors that are not unit length can result in errors or poor search results..
+* `cosine`: https://en.wikipedia.org/wiki/Cosine_similarity[Cosine similarity]. *NOTE*: the preferred way to perform cosine similarity is to normalize all vectors to unit length, and instead use DOT_PRODUCT. You should only use this function if you need to preserve the original vectors and cannot normalize them in advance.
+
+*N.B.* To use the following advanced parameters that customise the codec format
+and the hyper-parameter of the HNSW algorithm make sure you set this configuration in the solrconfig.xml:
+[source,xml]
+<config>
+<codecFactory class="solr.SchemaCodecFactory"/>
+...
+
+Here's how `DenseVectorField` can be configured with the advanced codec hyper-parameters:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine" codecFormat="Lucene90HnswVectorsFormat" hnswMaxConnections="10" hnswBeamWidth="40"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`codecFormat`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `Lucene90HnswVectorsFormat`
+|===
++
+(advanced) Specifies the knn codec implementation to use
++
+
+Accepted values: `Lucene90HnswVectorsFormat`.
+
+Please note that the `codecFormat` accepted values may change in future releases.
+
+
+
+[NOTE]
+Lucene index back-compatibility is only supported for the default codec.
+If you choose to customize the `codecFormat` in your schema, upgrading to a future version of Solr may require you to either switch back to the default codec and optimize your index to rewrite it into the default codec before upgrading, or re-build your entire index from scratch after upgrading.
+
+`hnswMaxConnections`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 16
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+Controls how many of the nearest neighbor candidates are connected to the new node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `M` from the later paper.
++
+Accepted values:
+Integer.
+
+`hnswBeamWidth`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 100
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+It is the number of nearest neighbor candidates to track while searching the graph for each newly inserted node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `efConstruction` from the later paper.
++
+Accepted values:
+Integer.
+
+DenseVectorField supports the attributes: `indexed`, `stored`.
+
+*N.B.* currently multivalue is not supported
+
+Here's how a `DenseVectorField` should be indexed:
+
+[.dynamic-tabs]
+--
+[example.tab-pane#json]
+====
+[.tab-label]*JSON*
+[source,json]
+----
+[{ "id": "1",
+"vector": [1.0, 2.5, 3.7, 4.1]
+},
+{ "id": "2",
+"vector": [1.5, 5.5, 6.7, 65.1]
+}
+]
+----
+====
+
+[example.tab-pane#xml]
+====
+[.tab-label]*XML*
+[source,xml]
+----
+<add>
+<doc>
+<field name="id">1</field>
+<field name="vector">1.0</field>
+<field name="vector">2.5</field>
+<field name="vector">3.7</field>
+<field name="vector">4.1</field>
+</doc>
+<doc>
+<field name="id">2</field>
+<field name="vector">1.5</field>
+<field name="vector">5.5</field>
+<field name="vector">6.7</field>
+<field name="vector">65.1</field>
+</doc>
+</add>
+----
+====
+
+[example.tab-pane#solrj]
+====
+[.tab-label]*SolrJ*
+[source,java,indent=0]
+----
+final SolrClient client = getSolrClient();
+
+final SolrInputDocument d1 = new SolrInputDocument();
+d1.setField("id", "1");
+d1.setField("vector", Arrays.asList(1.0f, 2.5f, 3.7f, 4.1f));
+
+
+final SolrInputDocument d2 = new SolrInputDocument();
+d2.setField("id", "2");
+d2.setField("vector", Arrays.asList(1.5f, 5.5f, 6.7f, 65.1f));
+
+client.add(Arrays.asList(d1, d2));
+----
+====
+--
+
+== Query Time
+This is the list of Apache Solr query approaches designed to support Neural Search:
+
+=== knn Query Parser
+The `knn` K-Nearest Neighbors query parser allows to find the k-nearest documents to the target vector according to indexed dense vectors in the given field.
+
+The score for a retrieved document is the approximate distance to the target vector(defined by the similarityFunction configured at indexing time).
+
+It takes the following parameters:
+
+`f`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory

Review comment:
       See also comment above, the structure for this means this should be "Required" in bold, and include "Default: none" if there is no default.

##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+

Review comment:
       This promises to discuss Neural Search Concepts, which IIUC includes a wide variety of topics and ideas. However, just like the name of the page, it's promising more than it delivers. There's mention of deep learning, but again we're not providing that - we're providing a way to index the _output_ of deep learning, which is then discussed. I think this section might need to be renamed and the following section on Deep Learning edited to be more focused on what Solr (via Lucene) *does* actually provide.

##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not be solved simply by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+
+=== DenseVectorField
+The Dense Vector field gives the possibility of indexing and searching dense vectors of float elements.
+
+e.g.
+
+`[1.0, 2.5, 3.7, 4.1]` (array of float elements)
+
+Here's how `DenseVectorField` should be configured in the schema:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`vectorDimension`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The dimension of the dense vector to pass in.
++
+Accepted values:
+Integer < = 1024.
+
+`similarityFunction`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `euclidean`
+|===
++
+Vector similarity function; used in search to return top K most similar vectors to a target vector.
++
+Accepted values: `euclidean`, `dot_product`  or `cosine`.
+
+* `euclidean`: https://en.wikipedia.org/wiki/Euclidean_distance[Euclidean distance]
+* `dot_product`: https://en.wikipedia.org/wiki/Dot_product[Dot product]. *NOTE*: this similarity is intended as an optimized way to perform cosine similarity. In order to use it, all vectors must be of unit length, including both document and query vectors. Using dot product with vectors that are not unit length can result in errors or poor search results..
+* `cosine`: https://en.wikipedia.org/wiki/Cosine_similarity[Cosine similarity]. *NOTE*: the preferred way to perform cosine similarity is to normalize all vectors to unit length, and instead use DOT_PRODUCT. You should only use this function if you need to preserve the original vectors and cannot normalize them in advance.
+
+*N.B.* To use the following advanced parameters that customise the codec format
+and the hyper-parameter of the HNSW algorithm make sure you set this configuration in the solrconfig.xml:
+[source,xml]
+<config>
+<codecFactory class="solr.SchemaCodecFactory"/>
+...
+
+Here's how `DenseVectorField` can be configured with the advanced codec hyper-parameters:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine" codecFormat="Lucene90HnswVectorsFormat" hnswMaxConnections="10" hnswBeamWidth="40"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`codecFormat`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `Lucene90HnswVectorsFormat`
+|===
++
+(advanced) Specifies the knn codec implementation to use
++
+
+Accepted values: `Lucene90HnswVectorsFormat`.
+
+Please note that the `codecFormat` accepted values may change in future releases.
+
+
+
+[NOTE]
+Lucene index back-compatibility is only supported for the default codec.
+If you choose to customize the `codecFormat` in your schema, upgrading to a future version of Solr may require you to either switch back to the default codec and optimize your index to rewrite it into the default codec before upgrading, or re-build your entire index from scratch after upgrading.
+
+`hnswMaxConnections`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 16
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+Controls how many of the nearest neighbor candidates are connected to the new node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `M` from the later paper.
++
+Accepted values:
+Integer.
+
+`hnswBeamWidth`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 100
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+It is the number of nearest neighbor candidates to track while searching the graph for each newly inserted node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `efConstruction` from the later paper.
++
+Accepted values:
+Integer.
+
+DenseVectorField supports the attributes: `indexed`, `stored`.
+
+*N.B.* currently multivalue is not supported
+
+Here's how a `DenseVectorField` should be indexed:
+
+[.dynamic-tabs]
+--
+[example.tab-pane#json]
+====
+[.tab-label]*JSON*
+[source,json]
+----
+[{ "id": "1",
+"vector": [1.0, 2.5, 3.7, 4.1]
+},
+{ "id": "2",
+"vector": [1.5, 5.5, 6.7, 65.1]
+}
+]
+----
+====
+
+[example.tab-pane#xml]
+====
+[.tab-label]*XML*
+[source,xml]
+----
+<add>
+<doc>
+<field name="id">1</field>
+<field name="vector">1.0</field>
+<field name="vector">2.5</field>
+<field name="vector">3.7</field>
+<field name="vector">4.1</field>
+</doc>
+<doc>
+<field name="id">2</field>
+<field name="vector">1.5</field>
+<field name="vector">5.5</field>
+<field name="vector">6.7</field>
+<field name="vector">65.1</field>
+</doc>
+</add>
+----
+====
+
+[example.tab-pane#solrj]
+====
+[.tab-label]*SolrJ*
+[source,java,indent=0]
+----
+final SolrClient client = getSolrClient();
+
+final SolrInputDocument d1 = new SolrInputDocument();
+d1.setField("id", "1");
+d1.setField("vector", Arrays.asList(1.0f, 2.5f, 3.7f, 4.1f));
+
+
+final SolrInputDocument d2 = new SolrInputDocument();
+d2.setField("id", "2");
+d2.setField("vector", Arrays.asList(1.5f, 5.5f, 6.7f, 65.1f));
+
+client.add(Arrays.asList(d1, d2));
+----
+====
+--
+
+== Query Time
+This is the list of Apache Solr query approaches designed to support Neural Search:
+
+=== knn Query Parser
+The `knn` K-Nearest Neighbors query parser allows to find the k-nearest documents to the target vector according to indexed dense vectors in the given field.
+
+The score for a retrieved document is the approximate distance to the target vector(defined by the similarityFunction configured at indexing time).
+
+It takes the following parameters:
+
+`f`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The DenseVectorField to search in.

Review comment:
       monospace other places...

##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not be solved simply by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+
+=== DenseVectorField
+The Dense Vector field gives the possibility of indexing and searching dense vectors of float elements.
+
+e.g.
+
+`[1.0, 2.5, 3.7, 4.1]` (array of float elements)
+
+Here's how `DenseVectorField` should be configured in the schema:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`vectorDimension`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The dimension of the dense vector to pass in.
++
+Accepted values:
+Integer < = 1024.
+
+`similarityFunction`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `euclidean`
+|===
++
+Vector similarity function; used in search to return top K most similar vectors to a target vector.
++
+Accepted values: `euclidean`, `dot_product`  or `cosine`.
+
+* `euclidean`: https://en.wikipedia.org/wiki/Euclidean_distance[Euclidean distance]
+* `dot_product`: https://en.wikipedia.org/wiki/Dot_product[Dot product]. *NOTE*: this similarity is intended as an optimized way to perform cosine similarity. In order to use it, all vectors must be of unit length, including both document and query vectors. Using dot product with vectors that are not unit length can result in errors or poor search results..
+* `cosine`: https://en.wikipedia.org/wiki/Cosine_similarity[Cosine similarity]. *NOTE*: the preferred way to perform cosine similarity is to normalize all vectors to unit length, and instead use DOT_PRODUCT. You should only use this function if you need to preserve the original vectors and cannot normalize them in advance.
+
+*N.B.* To use the following advanced parameters that customise the codec format
+and the hyper-parameter of the HNSW algorithm make sure you set this configuration in the solrconfig.xml:
+[source,xml]
+<config>
+<codecFactory class="solr.SchemaCodecFactory"/>
+...
+
+Here's how `DenseVectorField` can be configured with the advanced codec hyper-parameters:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine" codecFormat="Lucene90HnswVectorsFormat" hnswMaxConnections="10" hnswBeamWidth="40"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`codecFormat`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `Lucene90HnswVectorsFormat`
+|===
++
+(advanced) Specifies the knn codec implementation to use
++
+
+Accepted values: `Lucene90HnswVectorsFormat`.
+
+Please note that the `codecFormat` accepted values may change in future releases.
+
+
+
+[NOTE]
+Lucene index back-compatibility is only supported for the default codec.
+If you choose to customize the `codecFormat` in your schema, upgrading to a future version of Solr may require you to either switch back to the default codec and optimize your index to rewrite it into the default codec before upgrading, or re-build your entire index from scratch after upgrading.
+
+`hnswMaxConnections`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 16
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+Controls how many of the nearest neighbor candidates are connected to the new node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `M` from the later paper.
++
+Accepted values:
+Integer.
+
+`hnswBeamWidth`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 100
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+It is the number of nearest neighbor candidates to track while searching the graph for each newly inserted node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `efConstruction` from the later paper.
++
+Accepted values:
+Integer.
+
+DenseVectorField supports the attributes: `indexed`, `stored`.
+
+*N.B.* currently multivalue is not supported
+
+Here's how a `DenseVectorField` should be indexed:
+
+[.dynamic-tabs]
+--
+[example.tab-pane#json]
+====
+[.tab-label]*JSON*
+[source,json]
+----
+[{ "id": "1",
+"vector": [1.0, 2.5, 3.7, 4.1]
+},
+{ "id": "2",
+"vector": [1.5, 5.5, 6.7, 65.1]
+}
+]
+----
+====
+
+[example.tab-pane#xml]
+====
+[.tab-label]*XML*
+[source,xml]
+----
+<add>
+<doc>
+<field name="id">1</field>
+<field name="vector">1.0</field>
+<field name="vector">2.5</field>
+<field name="vector">3.7</field>
+<field name="vector">4.1</field>
+</doc>
+<doc>
+<field name="id">2</field>
+<field name="vector">1.5</field>
+<field name="vector">5.5</field>
+<field name="vector">6.7</field>
+<field name="vector">65.1</field>
+</doc>
+</add>
+----
+====
+
+[example.tab-pane#solrj]
+====
+[.tab-label]*SolrJ*
+[source,java,indent=0]
+----
+final SolrClient client = getSolrClient();
+
+final SolrInputDocument d1 = new SolrInputDocument();
+d1.setField("id", "1");
+d1.setField("vector", Arrays.asList(1.0f, 2.5f, 3.7f, 4.1f));
+
+
+final SolrInputDocument d2 = new SolrInputDocument();
+d2.setField("id", "2");
+d2.setField("vector", Arrays.asList(1.5f, 5.5f, 6.7f, 65.1f));
+
+client.add(Arrays.asList(d1, d2));
+----
+====
+--
+
+== Query Time
+This is the list of Apache Solr query approaches designed to support Neural Search:
+
+=== knn Query Parser
+The `knn` K-Nearest Neighbors query parser allows to find the k-nearest documents to the target vector according to indexed dense vectors in the given field.
+
+The score for a retrieved document is the approximate distance to the target vector(defined by the similarityFunction configured at indexing time).
+
+It takes the following parameters:
+
+`f`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The DenseVectorField to search in.
+
+`topK`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 10
+|===
++
+How many k-nearest results to return.

Review comment:
       Is it "k-nearest" or "K-Nearest" or "K-nearest"? You've got all of these within a few lines of each other.

##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not be solved simply by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+
+=== DenseVectorField
+The Dense Vector field gives the possibility of indexing and searching dense vectors of float elements.
+
+e.g.
+
+`[1.0, 2.5, 3.7, 4.1]` (array of float elements)
+
+Here's how `DenseVectorField` should be configured in the schema:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`vectorDimension`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The dimension of the dense vector to pass in.
++
+Accepted values:
+Integer < = 1024.
+
+`similarityFunction`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `euclidean`
+|===
++
+Vector similarity function; used in search to return top K most similar vectors to a target vector.
++
+Accepted values: `euclidean`, `dot_product`  or `cosine`.
+
+* `euclidean`: https://en.wikipedia.org/wiki/Euclidean_distance[Euclidean distance]
+* `dot_product`: https://en.wikipedia.org/wiki/Dot_product[Dot product]. *NOTE*: this similarity is intended as an optimized way to perform cosine similarity. In order to use it, all vectors must be of unit length, including both document and query vectors. Using dot product with vectors that are not unit length can result in errors or poor search results..
+* `cosine`: https://en.wikipedia.org/wiki/Cosine_similarity[Cosine similarity]. *NOTE*: the preferred way to perform cosine similarity is to normalize all vectors to unit length, and instead use DOT_PRODUCT. You should only use this function if you need to preserve the original vectors and cannot normalize them in advance.
+
+*N.B.* To use the following advanced parameters that customise the codec format
+and the hyper-parameter of the HNSW algorithm make sure you set this configuration in the solrconfig.xml:
+[source,xml]
+<config>
+<codecFactory class="solr.SchemaCodecFactory"/>
+...
+
+Here's how `DenseVectorField` can be configured with the advanced codec hyper-parameters:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine" codecFormat="Lucene90HnswVectorsFormat" hnswMaxConnections="10" hnswBeamWidth="40"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`codecFormat`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `Lucene90HnswVectorsFormat`
+|===
++
+(advanced) Specifies the knn codec implementation to use
++
+
+Accepted values: `Lucene90HnswVectorsFormat`.
+
+Please note that the `codecFormat` accepted values may change in future releases.
+
+
+
+[NOTE]
+Lucene index back-compatibility is only supported for the default codec.
+If you choose to customize the `codecFormat` in your schema, upgrading to a future version of Solr may require you to either switch back to the default codec and optimize your index to rewrite it into the default codec before upgrading, or re-build your entire index from scratch after upgrading.
+
+`hnswMaxConnections`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 16
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+Controls how many of the nearest neighbor candidates are connected to the new node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `M` from the later paper.
++
+Accepted values:
+Integer.
+
+`hnswBeamWidth`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 100
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+It is the number of nearest neighbor candidates to track while searching the graph for each newly inserted node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `efConstruction` from the later paper.
++
+Accepted values:
+Integer.
+
+DenseVectorField supports the attributes: `indexed`, `stored`.
+
+*N.B.* currently multivalue is not supported
+
+Here's how a `DenseVectorField` should be indexed:
+
+[.dynamic-tabs]
+--
+[example.tab-pane#json]
+====
+[.tab-label]*JSON*
+[source,json]
+----
+[{ "id": "1",
+"vector": [1.0, 2.5, 3.7, 4.1]
+},
+{ "id": "2",
+"vector": [1.5, 5.5, 6.7, 65.1]
+}
+]
+----
+====
+
+[example.tab-pane#xml]
+====
+[.tab-label]*XML*
+[source,xml]
+----
+<add>
+<doc>
+<field name="id">1</field>
+<field name="vector">1.0</field>
+<field name="vector">2.5</field>
+<field name="vector">3.7</field>
+<field name="vector">4.1</field>
+</doc>
+<doc>
+<field name="id">2</field>
+<field name="vector">1.5</field>
+<field name="vector">5.5</field>
+<field name="vector">6.7</field>
+<field name="vector">65.1</field>
+</doc>
+</add>
+----
+====
+
+[example.tab-pane#solrj]
+====
+[.tab-label]*SolrJ*
+[source,java,indent=0]
+----
+final SolrClient client = getSolrClient();
+
+final SolrInputDocument d1 = new SolrInputDocument();
+d1.setField("id", "1");
+d1.setField("vector", Arrays.asList(1.0f, 2.5f, 3.7f, 4.1f));
+
+
+final SolrInputDocument d2 = new SolrInputDocument();
+d2.setField("id", "2");
+d2.setField("vector", Arrays.asList(1.5f, 5.5f, 6.7f, 65.1f));
+
+client.add(Arrays.asList(d1, d2));
+----
+====
+--
+
+== Query Time
+This is the list of Apache Solr query approaches designed to support Neural Search:
+
+=== knn Query Parser
+The `knn` K-Nearest Neighbors query parser allows to find the k-nearest documents to the target vector according to indexed dense vectors in the given field.
+
+The score for a retrieved document is the approximate distance to the target vector(defined by the similarityFunction configured at indexing time).
+
+It takes the following parameters:
+
+`f`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The DenseVectorField to search in.
+
+`topK`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 10
+|===
++
+How many k-nearest results to return.
+
+Here's how to run a KNN search:
+
+[source,text]
+&q={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]
+
+The search results retrieved are the K-nearest to the vector in input `[1.0, 2.0, 3.0, 4.0]`, ranked by the similarityFunction configured at indexing time.
+
+==== Usage with Filter Queries
+The `knn` query parser can be used in filter queries:
+[source,text]
+&q=id:(1 2 3)&fq={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]
+
+The `knn` query parser can be used with filter queries:
+[source,text]
+&q={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]&fq=id:(1 2 3)
+
+[IMPORTANT]
+====
+When using `knn` in these scenarios make sure you have a clear understanding of how filter queries work in Apache Solr:
+
+The Ranked List of document IDs resulting from the main query `q` is intersected with the set of document IDs deriving from each filter query `fq`.
+
+e.g.
+
+Ranked List from `q`=`[ID1, ID4, ID2, ID10]` <intersects> Set from `fq`=`{ID3, ID2, ID9, ID4}` = `[ID4,ID2]`
+====
+
+
+==== Usage as Re-Ranking Query
+The `knn` query parser can be used to rerank first pass query results:
+[source,text]
+&q=id:(3 4 9 2)&rq={!rerank reRankQuery=$rqq reRankDocs=4 reRankWeight=1}&rqq={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]
+
+[IMPORTANT]
+====
+When using `knn` in reranking pay attention to the `topK` parameter.

Review comment:
       "Re-ranking" or "reranking"? You've got both in a few lines of each other.

##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not be solved simply by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+

Review comment:
       This sentence what will follow is a list, but it's really just one field.
   
   Why does "Index Time" have a sub-section "DenseVectorField" when that's the only item under it? Couldn't we just get rid of 1 level of headings and call this "DenseVectorField"? Or, "Dense Vector FieldType"? 

##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,733 @@
+= Neural Search

Review comment:
       Anyone else think it might be over-promising a bit so say that Solr has "neural search" when what we're talking about is dense vector support? Dense vector storage and retrieval are only one aspect of neural search, as I understand it, which means there are other aspects not addressed by the solutions documented in this page. I would prefer a page title like "Dense Vector Search" until we have more features for an overall "Neural Search" section.
   
   This is going to get some attention, so I want us to be very clear from the title of the page to the intro of the page to the content exactly what we are offering, and not seem like we're under-delivering a larger promise.

##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not be solved simply by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+
+=== DenseVectorField
+The Dense Vector field gives the possibility of indexing and searching dense vectors of float elements.
+
+e.g.
+
+`[1.0, 2.5, 3.7, 4.1]` (array of float elements)
+
+Here's how `DenseVectorField` should be configured in the schema:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`vectorDimension`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The dimension of the dense vector to pass in.
++
+Accepted values:
+Integer < = 1024.
+
+`similarityFunction`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `euclidean`
+|===
++
+Vector similarity function; used in search to return top K most similar vectors to a target vector.
++
+Accepted values: `euclidean`, `dot_product`  or `cosine`.
+
+* `euclidean`: https://en.wikipedia.org/wiki/Euclidean_distance[Euclidean distance]
+* `dot_product`: https://en.wikipedia.org/wiki/Dot_product[Dot product]. *NOTE*: this similarity is intended as an optimized way to perform cosine similarity. In order to use it, all vectors must be of unit length, including both document and query vectors. Using dot product with vectors that are not unit length can result in errors or poor search results..
+* `cosine`: https://en.wikipedia.org/wiki/Cosine_similarity[Cosine similarity]. *NOTE*: the preferred way to perform cosine similarity is to normalize all vectors to unit length, and instead use DOT_PRODUCT. You should only use this function if you need to preserve the original vectors and cannot normalize them in advance.
+
+*N.B.* To use the following advanced parameters that customise the codec format
+and the hyper-parameter of the HNSW algorithm make sure you set this configuration in the solrconfig.xml:
+[source,xml]
+<config>
+<codecFactory class="solr.SchemaCodecFactory"/>
+...
+
+Here's how `DenseVectorField` can be configured with the advanced codec hyper-parameters:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine" codecFormat="Lucene90HnswVectorsFormat" hnswMaxConnections="10" hnswBeamWidth="40"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`codecFormat`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `Lucene90HnswVectorsFormat`
+|===
++
+(advanced) Specifies the knn codec implementation to use
++
+
+Accepted values: `Lucene90HnswVectorsFormat`.
+
+Please note that the `codecFormat` accepted values may change in future releases.
+
+
+
+[NOTE]
+Lucene index back-compatibility is only supported for the default codec.
+If you choose to customize the `codecFormat` in your schema, upgrading to a future version of Solr may require you to either switch back to the default codec and optimize your index to rewrite it into the default codec before upgrading, or re-build your entire index from scratch after upgrading.
+
+`hnswMaxConnections`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 16
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+Controls how many of the nearest neighbor candidates are connected to the new node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `M` from the later paper.
++
+Accepted values:
+Integer.
+
+`hnswBeamWidth`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 100
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+It is the number of nearest neighbor candidates to track while searching the graph for each newly inserted node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `efConstruction` from the later paper.
++
+Accepted values:
+Integer.
+
+DenseVectorField supports the attributes: `indexed`, `stored`.
+
+*N.B.* currently multivalue is not supported
+
+Here's how a `DenseVectorField` should be indexed:
+
+[.dynamic-tabs]
+--
+[example.tab-pane#json]
+====
+[.tab-label]*JSON*
+[source,json]
+----
+[{ "id": "1",
+"vector": [1.0, 2.5, 3.7, 4.1]
+},
+{ "id": "2",
+"vector": [1.5, 5.5, 6.7, 65.1]
+}
+]
+----
+====
+
+[example.tab-pane#xml]
+====
+[.tab-label]*XML*
+[source,xml]
+----
+<add>
+<doc>
+<field name="id">1</field>
+<field name="vector">1.0</field>
+<field name="vector">2.5</field>
+<field name="vector">3.7</field>
+<field name="vector">4.1</field>
+</doc>
+<doc>
+<field name="id">2</field>
+<field name="vector">1.5</field>
+<field name="vector">5.5</field>
+<field name="vector">6.7</field>
+<field name="vector">65.1</field>
+</doc>
+</add>
+----
+====
+
+[example.tab-pane#solrj]
+====
+[.tab-label]*SolrJ*
+[source,java,indent=0]
+----
+final SolrClient client = getSolrClient();
+
+final SolrInputDocument d1 = new SolrInputDocument();
+d1.setField("id", "1");
+d1.setField("vector", Arrays.asList(1.0f, 2.5f, 3.7f, 4.1f));
+
+
+final SolrInputDocument d2 = new SolrInputDocument();
+d2.setField("id", "2");
+d2.setField("vector", Arrays.asList(1.5f, 5.5f, 6.7f, 65.1f));
+
+client.add(Arrays.asList(d1, d2));
+----
+====
+--
+
+== Query Time
+This is the list of Apache Solr query approaches designed to support Neural Search:
+
+=== knn Query Parser
+The `knn` K-Nearest Neighbors query parser allows to find the k-nearest documents to the target vector according to indexed dense vectors in the given field.
+
+The score for a retrieved document is the approximate distance to the target vector(defined by the similarityFunction configured at indexing time).
+
+It takes the following parameters:
+
+`f`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The DenseVectorField to search in.
+
+`topK`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 10
+|===
++
+How many k-nearest results to return.
+
+Here's how to run a KNN search:
+
+[source,text]
+&q={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]
+
+The search results retrieved are the K-nearest to the vector in input `[1.0, 2.0, 3.0, 4.0]`, ranked by the similarityFunction configured at indexing time.
+
+==== Usage with Filter Queries
+The `knn` query parser can be used in filter queries:
+[source,text]
+&q=id:(1 2 3)&fq={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]
+
+The `knn` query parser can be used with filter queries:
+[source,text]
+&q={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]&fq=id:(1 2 3)
+
+[IMPORTANT]
+====
+When using `knn` in these scenarios make sure you have a clear understanding of how filter queries work in Apache Solr:
+
+The Ranked List of document IDs resulting from the main query `q` is intersected with the set of document IDs deriving from each filter query `fq`.
+
+e.g.
+
+Ranked List from `q`=`[ID1, ID4, ID2, ID10]` <intersects> Set from `fq`=`{ID3, ID2, ID9, ID4}` = `[ID4,ID2]`
+====
+
+
+==== Usage as Re-Ranking Query
+The `knn` query parser can be used to rerank first pass query results:
+[source,text]
+&q=id:(3 4 9 2)&rq={!rerank reRankQuery=$rqq reRankDocs=4 reRankWeight=1}&rqq={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]
+
+[IMPORTANT]
+====
+When using `knn` in reranking pay attention to the `topK` parameter.
+
+The second pass score(deriving from knn) is calculated only if the document `d` from the first pass is within
+the K-nearest neighbors(*in the whole index*) of the target vector to search.
+
+This means the second pass `knn` is executed on the whole index anyway, which is a current limitation.
+
+The final ranked list of results will have the first pass score(main query `q`) added to the second pass score(the approximated similarityFunction distance to the target vector to search) multiplied by a multiplicative factor(reRankWeight).
+
+Details about using the ReRank Query Parser can be found in the <<query-re-ranking.adoc#,Query Re-Ranking>> section.
+====
+
+== Additional Neural Search Resources

Review comment:
       Could these be worked into the text in another way? This again advertises "Neural Search" features, but again only talks about dense vectors. I'm not the biggest fan of when people make a big section for "Additional resources" and it's only 2 links to blogs. Seems like this could be added into some earlier section as a sentence?

##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not be solved simply by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+
+=== DenseVectorField
+The Dense Vector field gives the possibility of indexing and searching dense vectors of float elements.
+
+e.g.
+

Review comment:
       This shouldn't ever be a line by itself. Introduce the example, perhaps by moving the parenthetical statement that's currently on the next line, shown after the example, as in:
   
   "For example, this array of float elements:"

##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not be solved simply by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+
+=== DenseVectorField
+The Dense Vector field gives the possibility of indexing and searching dense vectors of float elements.
+
+e.g.
+
+`[1.0, 2.5, 3.7, 4.1]` (array of float elements)
+
+Here's how `DenseVectorField` should be configured in the schema:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`vectorDimension`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The dimension of the dense vector to pass in.
++
+Accepted values:
+Integer < = 1024.
+
+`similarityFunction`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `euclidean`
+|===
++
+Vector similarity function; used in search to return top K most similar vectors to a target vector.
++
+Accepted values: `euclidean`, `dot_product`  or `cosine`.
+
+* `euclidean`: https://en.wikipedia.org/wiki/Euclidean_distance[Euclidean distance]
+* `dot_product`: https://en.wikipedia.org/wiki/Dot_product[Dot product]. *NOTE*: this similarity is intended as an optimized way to perform cosine similarity. In order to use it, all vectors must be of unit length, including both document and query vectors. Using dot product with vectors that are not unit length can result in errors or poor search results..
+* `cosine`: https://en.wikipedia.org/wiki/Cosine_similarity[Cosine similarity]. *NOTE*: the preferred way to perform cosine similarity is to normalize all vectors to unit length, and instead use DOT_PRODUCT. You should only use this function if you need to preserve the original vectors and cannot normalize them in advance.
+
+*N.B.* To use the following advanced parameters that customise the codec format
+and the hyper-parameter of the HNSW algorithm make sure you set this configuration in the solrconfig.xml:
+[source,xml]
+<config>
+<codecFactory class="solr.SchemaCodecFactory"/>
+...
+
+Here's how `DenseVectorField` can be configured with the advanced codec hyper-parameters:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine" codecFormat="Lucene90HnswVectorsFormat" hnswMaxConnections="10" hnswBeamWidth="40"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`codecFormat`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `Lucene90HnswVectorsFormat`
+|===
++
+(advanced) Specifies the knn codec implementation to use
++
+
+Accepted values: `Lucene90HnswVectorsFormat`.
+
+Please note that the `codecFormat` accepted values may change in future releases.
+
+
+
+[NOTE]
+Lucene index back-compatibility is only supported for the default codec.
+If you choose to customize the `codecFormat` in your schema, upgrading to a future version of Solr may require you to either switch back to the default codec and optimize your index to rewrite it into the default codec before upgrading, or re-build your entire index from scratch after upgrading.
+
+`hnswMaxConnections`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 16
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+Controls how many of the nearest neighbor candidates are connected to the new node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++

Review comment:
       These were already linked to earlier? Why repeat them again?

##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not be solved simply by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+
+=== DenseVectorField
+The Dense Vector field gives the possibility of indexing and searching dense vectors of float elements.
+
+e.g.
+
+`[1.0, 2.5, 3.7, 4.1]` (array of float elements)
+
+Here's how `DenseVectorField` should be configured in the schema:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`vectorDimension`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The dimension of the dense vector to pass in.
++
+Accepted values:
+Integer < = 1024.
+
+`similarityFunction`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `euclidean`
+|===
++
+Vector similarity function; used in search to return top K most similar vectors to a target vector.
++
+Accepted values: `euclidean`, `dot_product`  or `cosine`.
+
+* `euclidean`: https://en.wikipedia.org/wiki/Euclidean_distance[Euclidean distance]
+* `dot_product`: https://en.wikipedia.org/wiki/Dot_product[Dot product]. *NOTE*: this similarity is intended as an optimized way to perform cosine similarity. In order to use it, all vectors must be of unit length, including both document and query vectors. Using dot product with vectors that are not unit length can result in errors or poor search results..
+* `cosine`: https://en.wikipedia.org/wiki/Cosine_similarity[Cosine similarity]. *NOTE*: the preferred way to perform cosine similarity is to normalize all vectors to unit length, and instead use DOT_PRODUCT. You should only use this function if you need to preserve the original vectors and cannot normalize them in advance.
+
+*N.B.* To use the following advanced parameters that customise the codec format
+and the hyper-parameter of the HNSW algorithm make sure you set this configuration in the solrconfig.xml:
+[source,xml]
+<config>
+<codecFactory class="solr.SchemaCodecFactory"/>
+...
+
+Here's how `DenseVectorField` can be configured with the advanced codec hyper-parameters:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine" codecFormat="Lucene90HnswVectorsFormat" hnswMaxConnections="10" hnswBeamWidth="40"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`codecFormat`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `Lucene90HnswVectorsFormat`
+|===
++
+(advanced) Specifies the knn codec implementation to use
++
+
+Accepted values: `Lucene90HnswVectorsFormat`.
+
+Please note that the `codecFormat` accepted values may change in future releases.
+
+
+
+[NOTE]
+Lucene index back-compatibility is only supported for the default codec.
+If you choose to customize the `codecFormat` in your schema, upgrading to a future version of Solr may require you to either switch back to the default codec and optimize your index to rewrite it into the default codec before upgrading, or re-build your entire index from scratch after upgrading.
+
+`hnswMaxConnections`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 16
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+Controls how many of the nearest neighbor candidates are connected to the new node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `M` from the later paper.
++
+Accepted values:
+Integer.
+
+`hnswBeamWidth`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 100
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+It is the number of nearest neighbor candidates to track while searching the graph for each newly inserted node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++

Review comment:
       Again we're linking to these? 

##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not be solved simply by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+
+=== DenseVectorField
+The Dense Vector field gives the possibility of indexing and searching dense vectors of float elements.
+
+e.g.
+
+`[1.0, 2.5, 3.7, 4.1]` (array of float elements)
+
+Here's how `DenseVectorField` should be configured in the schema:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`vectorDimension`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The dimension of the dense vector to pass in.
++
+Accepted values:
+Integer < = 1024.
+
+`similarityFunction`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `euclidean`
+|===
++
+Vector similarity function; used in search to return top K most similar vectors to a target vector.
++
+Accepted values: `euclidean`, `dot_product`  or `cosine`.
+
+* `euclidean`: https://en.wikipedia.org/wiki/Euclidean_distance[Euclidean distance]
+* `dot_product`: https://en.wikipedia.org/wiki/Dot_product[Dot product]. *NOTE*: this similarity is intended as an optimized way to perform cosine similarity. In order to use it, all vectors must be of unit length, including both document and query vectors. Using dot product with vectors that are not unit length can result in errors or poor search results..
+* `cosine`: https://en.wikipedia.org/wiki/Cosine_similarity[Cosine similarity]. *NOTE*: the preferred way to perform cosine similarity is to normalize all vectors to unit length, and instead use DOT_PRODUCT. You should only use this function if you need to preserve the original vectors and cannot normalize them in advance.
+
+*N.B.* To use the following advanced parameters that customise the codec format
+and the hyper-parameter of the HNSW algorithm make sure you set this configuration in the solrconfig.xml:
+[source,xml]
+<config>
+<codecFactory class="solr.SchemaCodecFactory"/>
+...
+
+Here's how `DenseVectorField` can be configured with the advanced codec hyper-parameters:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine" codecFormat="Lucene90HnswVectorsFormat" hnswMaxConnections="10" hnswBeamWidth="40"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`codecFormat`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `Lucene90HnswVectorsFormat`
+|===
++
+(advanced) Specifies the knn codec implementation to use
++
+
+Accepted values: `Lucene90HnswVectorsFormat`.
+
+Please note that the `codecFormat` accepted values may change in future releases.
+
+
+
+[NOTE]
+Lucene index back-compatibility is only supported for the default codec.
+If you choose to customize the `codecFormat` in your schema, upgrading to a future version of Solr may require you to either switch back to the default codec and optimize your index to rewrite it into the default codec before upgrading, or re-build your entire index from scratch after upgrading.
+
+`hnswMaxConnections`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 16
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+Controls how many of the nearest neighbor candidates are connected to the new node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `M` from the later paper.
++
+Accepted values:
+Integer.
+
+`hnswBeamWidth`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 100
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+It is the number of nearest neighbor candidates to track while searching the graph for each newly inserted node.
++

Review comment:
       See above, this could be tightened up since we only support one codec....

##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not be solved simply by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+
+=== DenseVectorField
+The Dense Vector field gives the possibility of indexing and searching dense vectors of float elements.
+
+e.g.
+
+`[1.0, 2.5, 3.7, 4.1]` (array of float elements)
+

Review comment:
       See previous comment, remove the parenthetical and move it to the introduction to the example.

##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not be solved simply by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+
+=== DenseVectorField
+The Dense Vector field gives the possibility of indexing and searching dense vectors of float elements.
+
+e.g.
+
+`[1.0, 2.5, 3.7, 4.1]` (array of float elements)
+
+Here's how `DenseVectorField` should be configured in the schema:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`vectorDimension`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The dimension of the dense vector to pass in.
++
+Accepted values:
+Integer < = 1024.
+
+`similarityFunction`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `euclidean`
+|===
++
+Vector similarity function; used in search to return top K most similar vectors to a target vector.
++
+Accepted values: `euclidean`, `dot_product`  or `cosine`.
+
+* `euclidean`: https://en.wikipedia.org/wiki/Euclidean_distance[Euclidean distance]
+* `dot_product`: https://en.wikipedia.org/wiki/Dot_product[Dot product]. *NOTE*: this similarity is intended as an optimized way to perform cosine similarity. In order to use it, all vectors must be of unit length, including both document and query vectors. Using dot product with vectors that are not unit length can result in errors or poor search results..
+* `cosine`: https://en.wikipedia.org/wiki/Cosine_similarity[Cosine similarity]. *NOTE*: the preferred way to perform cosine similarity is to normalize all vectors to unit length, and instead use DOT_PRODUCT. You should only use this function if you need to preserve the original vectors and cannot normalize them in advance.
+
+*N.B.* To use the following advanced parameters that customise the codec format
+and the hyper-parameter of the HNSW algorithm make sure you set this configuration in the solrconfig.xml:
+[source,xml]
+<config>
+<codecFactory class="solr.SchemaCodecFactory"/>
+...
+
+Here's how `DenseVectorField` can be configured with the advanced codec hyper-parameters:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine" codecFormat="Lucene90HnswVectorsFormat" hnswMaxConnections="10" hnswBeamWidth="40"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`codecFormat`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `Lucene90HnswVectorsFormat`
+|===
++
+(advanced) Specifies the knn codec implementation to use
++
+
+Accepted values: `Lucene90HnswVectorsFormat`.
+
+Please note that the `codecFormat` accepted values may change in future releases.
+
+
+
+[NOTE]
+Lucene index back-compatibility is only supported for the default codec.
+If you choose to customize the `codecFormat` in your schema, upgrading to a future version of Solr may require you to either switch back to the default codec and optimize your index to rewrite it into the default codec before upgrading, or re-build your entire index from scratch after upgrading.
+
+`hnswMaxConnections`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 16
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+Controls how many of the nearest neighbor candidates are connected to the new node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `M` from the later paper.
++
+Accepted values:
+Integer.
+
+`hnswBeamWidth`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 100
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+It is the number of nearest neighbor candidates to track while searching the graph for each newly inserted node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `efConstruction` from the later paper.
++
+Accepted values:
+Integer.
+
+DenseVectorField supports the attributes: `indexed`, `stored`.
+
+*N.B.* currently multivalue is not supported

Review comment:
       Again, let's be consistent with other parts of the Ref Guide with regard to how we make notes - use the asciidoctor NOTE syntax (or INFO, or TIP, etc., whichever is most appropriate).




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] cpoerschke commented on a change in pull request #476: SOLR-15880

Posted by GitBox <gi...@apache.org>.
cpoerschke commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r786907068



##########
File path: solr/core/src/java/org/apache/solr/core/SchemaCodecFactory.java
##########
@@ -114,6 +118,26 @@ public DocValuesFormat getDocValuesFormatForField(String field) {
         }
         return super.getDocValuesFormatForField(field);
       }
+
+      @Override
+      public KnnVectorsFormat getKnnVectorsFormatForField(String field) {
+        final SchemaField schemaField = core.getLatestSchema().getFieldOrNull(field);
+        FieldType fieldType = (schemaField == null ? null : schemaField.getType());
+        if (fieldType != null && fieldType instanceof DenseVectorField) {

Review comment:
       I think the null check can be omitted since the `instanceof` would evaluate to `false` if `fieldType` was null.
   ```suggestion
           if (fieldType instanceof DenseVectorField) {
   ```

##########
File path: solr/core/src/java/org/apache/solr/schema/DenseVectorField.java
##########
@@ -0,0 +1,279 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.solr.schema;
+
+import org.apache.lucene.codecs.lucene90.Lucene90HnswVectorsFormat;
+import org.apache.lucene.document.KnnVectorField;
+import org.apache.lucene.index.IndexableField;
+import org.apache.lucene.index.VectorSimilarityFunction;
+import org.apache.lucene.queries.function.ValueSource;
+import org.apache.lucene.search.KnnVectorQuery;
+import org.apache.lucene.search.Query;
+import org.apache.lucene.search.SortField;
+import org.apache.lucene.util.hnsw.HnswGraph;
+import org.apache.solr.common.SolrException;
+import org.apache.solr.search.QParser;
+import org.apache.solr.uninverting.UninvertingReader;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
+
+import static java.util.Optional.ofNullable;
+import static org.apache.lucene.codecs.lucene90.Lucene90HnswVectorsFormat.DEFAULT_BEAM_WIDTH;
+import static org.apache.lucene.codecs.lucene90.Lucene90HnswVectorsFormat.DEFAULT_MAX_CONN;
+
+/**
+ * Provides a field type to support Lucene's {@link
+ * org.apache.lucene.document.KnnVectorField}.
+ * See {@link org.apache.lucene.search.KnnVectorQuery} for more details.
+ * It supports a fixed cardinality dimension for the vector and a fixed similarity function.
+ * The default similarity is EUCLIDEAN_HNSW (L2).
+ * The default index codec format is specified in the Lucene Codec constructor.
+ * For Lucene 9.0 e.g.
+ * See {@link org.apache.lucene.codecs.lucene90.Lucene90Codec}
+ * Currently only {@link org.apache.lucene.codecs.lucene90.Lucene90HnswVectorsFormat} is supported for
+ * advanced hyper-parameter customisation.
+ * See {@link org.apache.lucene.util.hnsw.HnswGraph} for more details about the implementation. 
+ *
+ * <br>
+ * Only {@code Indexed} and {@code Stored} attributes are supported.
+ */
+public class DenseVectorField extends FloatPointField {
+
+    static final String KNN_VECTOR_DIMENSION = "vectorDimension";
+    static final String KNN_SIMILARITY_FUNCTION = "similarityFunction";
+    
+    static final String CODEC_FORMAT = "codecFormat";
+    static final String HNSW_MAX_CONNECTIONS = "hnswMaxConnections";
+    static final String HNSW_BEAM_WIDTH = "hnswBeamWidth";
+
+    private int dimension;
+    private VectorSimilarityFunction similarityFunction;
+    private VectorSimilarityFunction DEFAULT_SIMILARITY = VectorSimilarityFunction.EUCLIDEAN;
+
+    private String codecFormat;
+    /**
+     * This parameter is coupled with the {@link Lucene90HnswVectorsFormat} format implementation.
+     * Controls how many of the nearest neighbor candidates are connected to the new node. Defaults to
+     * {@link Lucene90HnswVectorsFormat#DEFAULT_MAX_CONN}. See {@link HnswGraph} for more details.
+     */
+    private int hnswMaxConn;
+    /**
+     * This parameter is coupled with the {@link Lucene90HnswVectorsFormat} format implementation.
+     * The number of candidate neighbors to track while searching the graph for each newly inserted
+     * node. Defaults to to {@link Lucene90HnswVectorsFormat#DEFAULT_BEAM_WIDTH}. See {@link
+     * HnswGraph} for details.
+     */
+    private int hnswBeamWidth;
+
+    public DenseVectorField() {
+        super();
+    }
+    
+    public DenseVectorField(int dimension) {
+        super();
+        this.dimension = dimension;
+        this.similarityFunction = DEFAULT_SIMILARITY;
+    }
+    
+    public DenseVectorField(int dimension, VectorSimilarityFunction similarityFunction) {
+        super();
+        this.dimension = dimension;
+        this.similarityFunction = similarityFunction;
+    }
+
+    @Override
+    public void init(IndexSchema schema, Map<String, String> args) {
+        this.dimension = ofNullable(args.get(KNN_VECTOR_DIMENSION))
+                .map(value -> Integer.parseInt(value))
+                .orElseThrow(() -> new SolrException(SolrException.ErrorCode.SERVER_ERROR, "the vector dimension is a mandatory parameter"));
+        args.remove(KNN_VECTOR_DIMENSION);
+
+        this.similarityFunction = ofNullable(args.get(KNN_SIMILARITY_FUNCTION))
+                .map(value -> VectorSimilarityFunction.valueOf(value.toUpperCase(Locale.ROOT)))
+                .orElse(DEFAULT_SIMILARITY);
+        args.remove(KNN_SIMILARITY_FUNCTION);
+
+        this.codecFormat = args.get(CODEC_FORMAT);
+        args.remove(CODEC_FORMAT);
+
+        this.hnswMaxConn = ofNullable(args.get(HNSW_MAX_CONNECTIONS))
+                .map(value -> Integer.parseInt(value))
+                .orElse(DEFAULT_MAX_CONN);
+        args.remove(HNSW_MAX_CONNECTIONS);
+
+        this.hnswBeamWidth = ofNullable(args.get(HNSW_BEAM_WIDTH))
+                .map(value -> Integer.parseInt(value))
+                .orElse(DEFAULT_BEAM_WIDTH);
+        args.remove(HNSW_BEAM_WIDTH);
+
+        this.properties &= ~MULTIVALUED;
+        this.properties &= ~UNINVERTIBLE;
+        
+        super.init(schema, args);
+    }
+
+    public int getDimension() {
+        return dimension;
+    }
+
+    public VectorSimilarityFunction getSimilarityFunction() {
+        return similarityFunction;
+    }
+
+    public String getCodecFormat() {
+        return codecFormat;
+    }
+
+    public Integer getHnswMaxConn() {
+        return hnswMaxConn;
+    }
+
+    public Integer getHnswBeamWidth() {
+        return hnswBeamWidth;
+    }
+
+    @Override
+    public void checkSchemaField(final SchemaField field) throws SolrException {
+        super.checkSchemaField(field);
+        if (field.multiValued()) {
+            throw new SolrException(SolrException.ErrorCode.SERVER_ERROR,
+                    getClass().getSimpleName() + " fields can not be multiValued: " + field.getName());
+        }
+
+        if (field.hasDocValues()) {
+            throw new SolrException(SolrException.ErrorCode.SERVER_ERROR,
+                    getClass().getSimpleName() + " fields can not have docValues: " + field.getName());
+        }
+    }
+    
+    public List<IndexableField> createFields(SchemaField field, Object value) {
+        ArrayList<IndexableField> fields = new ArrayList<>();
+        float[] parsedVector;
+        try {
+            parsedVector = parseVector(value);
+        } catch (RuntimeException e) {
+            throw new SolrException(SolrException.ErrorCode.SERVER_ERROR, "Error while creating field '" + field + "' from value '" + value + "', expected format:'[f1, f2, f3...fn]' e.g. [1.0, 3.4, 5.6]", e);
+        }
+
+        if (field.indexed()) {
+            fields.add(createField(field, parsedVector));
+        }
+        if (field.stored()) {
+            fields.ensureCapacity(parsedVector.length + 1);
+            for (float vectorElement : parsedVector) {
+                fields.add(getStoredField(field, vectorElement));
+            }
+        }
+        return fields;
+    }
+
+    @Override
+    public IndexableField createField(SchemaField field, Object parsedVector) {
+        if (parsedVector == null) return null;
+        float[] typedVector = (float[]) parsedVector;
+        return new KnnVectorField(field.getName(), typedVector, similarityFunction);
+    }
+
+    /**
+     * Index Time Parsing
+     * The inputValue is an ArrayList with a type that dipends on the loader used:

Review comment:
       ```suggestion
        * The inputValue is an ArrayList with a type that depends on the loader used:
   ```

##########
File path: solr/core/src/java/org/apache/solr/schema/DenseVectorField.java
##########
@@ -0,0 +1,256 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.solr.schema;
+
+import org.apache.lucene.codecs.lucene90.Lucene90HnswVectorsFormat;
+import org.apache.lucene.document.KnnVectorField;
+import org.apache.lucene.index.IndexableField;
+import org.apache.lucene.index.VectorSimilarityFunction;
+import org.apache.lucene.queries.function.ValueSource;
+import org.apache.lucene.search.KnnVectorQuery;
+import org.apache.lucene.search.Query;
+import org.apache.lucene.search.SortField;
+import org.apache.lucene.util.hnsw.HnswGraph;
+import org.apache.solr.common.SolrException;
+import org.apache.solr.search.QParser;
+import org.apache.solr.uninverting.UninvertingReader;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
+
+import static java.util.Optional.ofNullable;
+import static org.apache.lucene.codecs.lucene90.Lucene90HnswVectorsFormat.DEFAULT_BEAM_WIDTH;
+import static org.apache.lucene.codecs.lucene90.Lucene90HnswVectorsFormat.DEFAULT_MAX_CONN;
+
+/**
+ * Provides a field type to support Lucene's {@link
+ * org.apache.lucene.document.KnnVectorField}.
+ * See {@link org.apache.lucene.search.KnnVectorQuery} for more details.
+ * It supports a fixed cardinality dimension for the vector and a fixed similarity function.
+ * The default similarity is EUCLIDEAN_HNSW (L2).
+ * The default index codec format is specified in the Lucene Codec constructor.
+ * For Lucene 9.0 e.g.
+ * See {@link org.apache.lucene.codecs.lucene90.Lucene90Codec}
+ * Currently only {@link org.apache.lucene.codecs.lucene90.Lucene90HnswVectorsFormat} is supported for
+ * advanced hyper-parameter customisation.
+ * See {@link org.apache.lucene.util.hnsw.HnswGraph} for more details about the implementation. 
+ *
+ * <br>
+ * Only {@code Indexed} and {@code Stored} attributes are supported.
+ */
+public class DenseVectorField extends FloatPointField {
+
+    static final String KNN_VECTOR_DIMENSION = "vectorDimension";
+    static final String KNN_SIMILARITY_FUNCTION = "similarityFunction";
+    
+    static final String CODEC_FORMAT = "codecFormat";
+    static final String HNSW_MAX_CONNECTIONS = "hnswMaxConnections";
+    static final String HNSW_BEAM_WIDTH = "hnswBeamWidth";
+
+    int dimension;
+    VectorSimilarityFunction similarityFunction;
+    VectorSimilarityFunction DEFAULT_SIMILARITY = VectorSimilarityFunction.EUCLIDEAN;
+
+    String codecFormat;
+    /**
+     * This parameter is coupled with the {@link Lucene90HnswVectorsFormat} format implementation.
+     * Controls how many of the nearest neighbor candidates are connected to the new node. Defaults to
+     * {@link Lucene90HnswVectorsFormat#DEFAULT_MAX_CONN}. See {@link HnswGraph} for more details.
+     */
+    int hnswMaxConn;
+    /**
+     * This parameter is coupled with the {@link Lucene90HnswVectorsFormat} format implementation.
+     * The number of candidate neighbors to track while searching the graph for each newly inserted
+     * node. Defaults to to {@link Lucene90HnswVectorsFormat#DEFAULT_BEAM_WIDTH}. See {@link
+     * HnswGraph} for details.
+     */
+    int hnswBeamWidth;
+
+    @Override
+    public void init(IndexSchema schema, Map<String, String> args) {
+        this.dimension = ofNullable(args.get(KNN_VECTOR_DIMENSION))
+                .map(value -> Integer.parseInt(value))
+                .orElseThrow(() -> new SolrException(SolrException.ErrorCode.SERVER_ERROR, "the vector dimension is a mandatory parameter"));
+        args.remove(KNN_VECTOR_DIMENSION);
+
+        this.similarityFunction = ofNullable(args.get(KNN_SIMILARITY_FUNCTION))
+                .map(value -> VectorSimilarityFunction.valueOf(value.toUpperCase(Locale.ROOT)))
+                .orElse(DEFAULT_SIMILARITY);
+        args.remove(KNN_SIMILARITY_FUNCTION);
+
+        this.codecFormat = args.get(CODEC_FORMAT);
+        args.remove(CODEC_FORMAT);
+
+        this.hnswMaxConn = ofNullable(args.get(HNSW_MAX_CONNECTIONS))
+                .map(value -> Integer.parseInt(value))
+                .orElse(DEFAULT_MAX_CONN);
+        args.remove(HNSW_MAX_CONNECTIONS);
+
+        this.hnswBeamWidth = ofNullable(args.get(HNSW_BEAM_WIDTH))
+                .map(value -> Integer.parseInt(value))
+                .orElse(DEFAULT_BEAM_WIDTH);
+        args.remove(HNSW_BEAM_WIDTH);
+
+        this.properties &= ~MULTIVALUED;
+        this.properties &= ~UNINVERTIBLE;
+        
+        super.init(schema, args);
+    }
+
+    public int getDimension() {
+        return dimension;
+    }
+
+    public String getCodecFormat() {
+        return codecFormat;
+    }
+
+    public Integer getHnswMaxConn() {
+        return hnswMaxConn;
+    }
+
+    public Integer getHnswBeamWidth() {
+        return hnswBeamWidth;
+    }
+
+    @Override
+    public void checkSchemaField(final SchemaField field) throws SolrException {
+        super.checkSchemaField(field);
+        if (field.multiValued()) {
+            throw new SolrException(SolrException.ErrorCode.SERVER_ERROR,
+                    getClass().getSimpleName() + " fields can not be multiValued: " + field.getName());
+        }
+
+        if (field.hasDocValues()) {
+            throw new SolrException(SolrException.ErrorCode.SERVER_ERROR,
+                    getClass().getSimpleName() + " fields can not have docValues: " + field.getName());
+        }
+    }
+    
+    public List<IndexableField> createFields(SchemaField field, Object value) {
+        List<IndexableField> fields = new ArrayList<>();
+        float[] parsedVector;
+        try {
+            parsedVector = parseVector(value);
+        } catch (RuntimeException e) {
+            throw new SolrException(SolrException.ErrorCode.SERVER_ERROR, "Error while creating field '" + field + "' from value '" + value + "', expected format:'[f1, f2, f3...fn]' e.g. [1.0, 3.4, 5.6]", e);
+        }
+
+        if (field.indexed()) {
+            fields.add(createField(field, parsedVector));
+        }
+        if (field.stored()) {
+            for (float vectorElement : parsedVector) {
+                fields.add(getStoredField(field, vectorElement));
+            }
+        }
+        return fields;
+    }
+
+    @Override
+    public IndexableField createField(SchemaField field, Object parsedVector) {
+        float[] typedVector;
+        if (parsedVector == null) return null;
+        typedVector = (float[]) parsedVector;
+        return new KnnVectorField(field.getName(), typedVector, similarityFunction);
+    }
+
+    /**
+     * Index Time Parsing
+     * The inputValue is an ArrayList with a type that dipends on the loader used:
+     * - {@link org.apache.solr.handler.loader.XMLLoader}, {@link org.apache.solr.handler.loader.CSVLoader} produces an ArrayList of String
+     * - {@link org.apache.solr.handler.loader.JsonLoader} produces an ArrayList of Double
+     * - {@link org.apache.solr.handler.loader.JavabinLoader} produces an ArrayList of Float
+     *
+     * @param inputValue - An {@link ArrayList} containing the elements of the vector
+     * @return the vector parsed
+     */
+    float[] parseVector(Object inputValue) {
+        if (!(inputValue instanceof List)) {
+            throw new SolrException(SolrException.ErrorCode.BAD_REQUEST, "incorrect vector format." +
+                    " The expected format is an array :'[f1,f2..f3]' where each element f is a float");
+        }
+        List<?> inputVector = (List<?>) inputValue;
+        if (inputVector.size() != dimension) {
+            throw new SolrException(SolrException.ErrorCode.BAD_REQUEST, "incorrect vector dimension." +
+                    " The vector value has size "
+                    + inputVector.size() + " while it is expected a vector with size " + dimension);
+        }
+
+        float[] vector = new float[dimension];
+        if (inputVector.get(0) instanceof CharSequence) {
+            for (int i = 0; i < dimension; i++) {
+                try {
+                    vector[i] = Float.parseFloat(inputVector.get(i).toString());
+                } catch (NumberFormatException e) {
+                    throw new SolrException(SolrException.ErrorCode.BAD_REQUEST, "incorrect vector element: '" + inputVector.get(i) +
+                            "'. The expected format is:'[f1,f2..f3]' where each element f is a float");
+                }
+            }
+        } else if (inputVector.get(0) instanceof Number) {
+            for (int i = 0; i < dimension; i++) {
+                vector[i] = ((Number) inputVector.get(i)).floatValue();
+            }
+        }
+
+        return vector;
+    }
+
+    @Override
+    public UninvertingReader.Type getUninversionType(SchemaField sf) {
+        return null;
+    }
+
+    @Override
+    public ValueSource getValueSource(SchemaField field, QParser parser) {
+        throw new SolrException(SolrException.ErrorCode.BAD_REQUEST,
+                "Function queries are not supported for Dense Vector fields.");
+    }
+
+    public Query getKnnVectorQuery(SchemaField field, float[] vectorToSearch, int topK) {
+        return new KnnVectorQuery(field.getName(), vectorToSearch, topK);
+    }
+
+    /**
+     * Not Supported

Review comment:
       > can't find this one, can you elaborate it a bit?
   
   Something like this is what I meant.
   
   ```suggestion
        * Not Supported. Please use the {!knn} query parser to run K nearest neighbors search queries.
   ```




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880: K Nearest Neighbors Search

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r787655709



##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not be solved simply by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+
+=== DenseVectorField
+The Dense Vector field gives the possibility of indexing and searching dense vectors of float elements.
+
+e.g.
+
+`[1.0, 2.5, 3.7, 4.1]` (array of float elements)
+
+Here's how `DenseVectorField` should be configured in the schema:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`vectorDimension`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The dimension of the dense vector to pass in.
++
+Accepted values:
+Integer < = 1024.
+
+`similarityFunction`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `euclidean`
+|===
++
+Vector similarity function; used in search to return top K most similar vectors to a target vector.
++
+Accepted values: `euclidean`, `dot_product`  or `cosine`.
+
+* `euclidean`: https://en.wikipedia.org/wiki/Euclidean_distance[Euclidean distance]
+* `dot_product`: https://en.wikipedia.org/wiki/Dot_product[Dot product]. *NOTE*: this similarity is intended as an optimized way to perform cosine similarity. In order to use it, all vectors must be of unit length, including both document and query vectors. Using dot product with vectors that are not unit length can result in errors or poor search results..
+* `cosine`: https://en.wikipedia.org/wiki/Cosine_similarity[Cosine similarity]. *NOTE*: the preferred way to perform cosine similarity is to normalize all vectors to unit length, and instead use DOT_PRODUCT. You should only use this function if you need to preserve the original vectors and cannot normalize them in advance.
+
+*N.B.* To use the following advanced parameters that customise the codec format
+and the hyper-parameter of the HNSW algorithm make sure you set this configuration in the solrconfig.xml:
+[source,xml]
+<config>
+<codecFactory class="solr.SchemaCodecFactory"/>
+...
+
+Here's how `DenseVectorField` can be configured with the advanced codec hyper-parameters:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine" codecFormat="Lucene90HnswVectorsFormat" hnswMaxConnections="10" hnswBeamWidth="40"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`codecFormat`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `Lucene90HnswVectorsFormat`
+|===
++
+(advanced) Specifies the knn codec implementation to use
++
+
+Accepted values: `Lucene90HnswVectorsFormat`.
+
+Please note that the `codecFormat` accepted values may change in future releases.
+
+
+
+[NOTE]
+Lucene index back-compatibility is only supported for the default codec.
+If you choose to customize the `codecFormat` in your schema, upgrading to a future version of Solr may require you to either switch back to the default codec and optimize your index to rewrite it into the default codec before upgrading, or re-build your entire index from scratch after upgrading.
+
+`hnswMaxConnections`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 16
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+Controls how many of the nearest neighbor candidates are connected to the new node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `M` from the later paper.
++
+Accepted values:
+Integer.
+
+`hnswBeamWidth`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 100
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+It is the number of nearest neighbor candidates to track while searching the graph for each newly inserted node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `efConstruction` from the later paper.
++
+Accepted values:
+Integer.
+
+DenseVectorField supports the attributes: `indexed`, `stored`.

Review comment:
       Agreed!




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880: K Nearest Neighbors Search

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r787642584



##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not be solved simply by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+
+=== DenseVectorField
+The Dense Vector field gives the possibility of indexing and searching dense vectors of float elements.
+
+e.g.
+
+`[1.0, 2.5, 3.7, 4.1]` (array of float elements)
+
+Here's how `DenseVectorField` should be configured in the schema:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`vectorDimension`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++

Review comment:
       Done!




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880: K Nearest Neighbors Search

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r787663413



##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not be solved simply by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+
+=== DenseVectorField
+The Dense Vector field gives the possibility of indexing and searching dense vectors of float elements.
+
+e.g.
+
+`[1.0, 2.5, 3.7, 4.1]` (array of float elements)
+
+Here's how `DenseVectorField` should be configured in the schema:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`vectorDimension`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The dimension of the dense vector to pass in.
++
+Accepted values:
+Integer < = 1024.
+
+`similarityFunction`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `euclidean`
+|===
++
+Vector similarity function; used in search to return top K most similar vectors to a target vector.
++
+Accepted values: `euclidean`, `dot_product`  or `cosine`.
+
+* `euclidean`: https://en.wikipedia.org/wiki/Euclidean_distance[Euclidean distance]
+* `dot_product`: https://en.wikipedia.org/wiki/Dot_product[Dot product]. *NOTE*: this similarity is intended as an optimized way to perform cosine similarity. In order to use it, all vectors must be of unit length, including both document and query vectors. Using dot product with vectors that are not unit length can result in errors or poor search results..
+* `cosine`: https://en.wikipedia.org/wiki/Cosine_similarity[Cosine similarity]. *NOTE*: the preferred way to perform cosine similarity is to normalize all vectors to unit length, and instead use DOT_PRODUCT. You should only use this function if you need to preserve the original vectors and cannot normalize them in advance.
+
+*N.B.* To use the following advanced parameters that customise the codec format
+and the hyper-parameter of the HNSW algorithm make sure you set this configuration in the solrconfig.xml:
+[source,xml]
+<config>
+<codecFactory class="solr.SchemaCodecFactory"/>
+...
+
+Here's how `DenseVectorField` can be configured with the advanced codec hyper-parameters:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine" codecFormat="Lucene90HnswVectorsFormat" hnswMaxConnections="10" hnswBeamWidth="40"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`codecFormat`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `Lucene90HnswVectorsFormat`
+|===
++
+(advanced) Specifies the knn codec implementation to use
++
+
+Accepted values: `Lucene90HnswVectorsFormat`.
+
+Please note that the `codecFormat` accepted values may change in future releases.
+
+
+
+[NOTE]
+Lucene index back-compatibility is only supported for the default codec.
+If you choose to customize the `codecFormat` in your schema, upgrading to a future version of Solr may require you to either switch back to the default codec and optimize your index to rewrite it into the default codec before upgrading, or re-build your entire index from scratch after upgrading.
+
+`hnswMaxConnections`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 16
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+Controls how many of the nearest neighbor candidates are connected to the new node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `M` from the later paper.
++
+Accepted values:
+Integer.
+
+`hnswBeamWidth`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 100
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+It is the number of nearest neighbor candidates to track while searching the graph for each newly inserted node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `efConstruction` from the later paper.
++
+Accepted values:
+Integer.
+
+DenseVectorField supports the attributes: `indexed`, `stored`.
+
+*N.B.* currently multivalue is not supported
+
+Here's how a `DenseVectorField` should be indexed:
+
+[.dynamic-tabs]
+--
+[example.tab-pane#json]
+====
+[.tab-label]*JSON*
+[source,json]
+----
+[{ "id": "1",
+"vector": [1.0, 2.5, 3.7, 4.1]
+},
+{ "id": "2",
+"vector": [1.5, 5.5, 6.7, 65.1]
+}
+]
+----
+====
+
+[example.tab-pane#xml]
+====
+[.tab-label]*XML*
+[source,xml]
+----
+<add>
+<doc>
+<field name="id">1</field>
+<field name="vector">1.0</field>
+<field name="vector">2.5</field>
+<field name="vector">3.7</field>
+<field name="vector">4.1</field>
+</doc>
+<doc>
+<field name="id">2</field>
+<field name="vector">1.5</field>
+<field name="vector">5.5</field>
+<field name="vector">6.7</field>
+<field name="vector">65.1</field>
+</doc>
+</add>
+----
+====
+
+[example.tab-pane#solrj]
+====
+[.tab-label]*SolrJ*
+[source,java,indent=0]
+----
+final SolrClient client = getSolrClient();
+
+final SolrInputDocument d1 = new SolrInputDocument();
+d1.setField("id", "1");
+d1.setField("vector", Arrays.asList(1.0f, 2.5f, 3.7f, 4.1f));
+
+
+final SolrInputDocument d2 = new SolrInputDocument();
+d2.setField("id", "2");
+d2.setField("vector", Arrays.asList(1.5f, 5.5f, 6.7f, 65.1f));
+
+client.add(Arrays.asList(d1, d2));
+----
+====
+--
+
+== Query Time
+This is the list of Apache Solr query approaches designed to support Neural Search:
+
+=== knn Query Parser
+The `knn` K-Nearest Neighbors query parser allows to find the k-nearest documents to the target vector according to indexed dense vectors in the given field.
+
+The score for a retrieved document is the approximate distance to the target vector(defined by the similarityFunction configured at indexing time).
+
+It takes the following parameters:
+
+`f`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The DenseVectorField to search in.
+
+`topK`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 10
+|===
++
+How many k-nearest results to return.
+
+Here's how to run a KNN search:
+
+[source,text]
+&q={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]
+
+The search results retrieved are the K-nearest to the vector in input `[1.0, 2.0, 3.0, 4.0]`, ranked by the similarityFunction configured at indexing time.
+
+==== Usage with Filter Queries
+The `knn` query parser can be used in filter queries:
+[source,text]
+&q=id:(1 2 3)&fq={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]
+
+The `knn` query parser can be used with filter queries:
+[source,text]
+&q={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]&fq=id:(1 2 3)
+
+[IMPORTANT]
+====
+When using `knn` in these scenarios make sure you have a clear understanding of how filter queries work in Apache Solr:
+
+The Ranked List of document IDs resulting from the main query `q` is intersected with the set of document IDs deriving from each filter query `fq`.
+
+e.g.
+
+Ranked List from `q`=`[ID1, ID4, ID2, ID10]` <intersects> Set from `fq`=`{ID3, ID2, ID9, ID4}` = `[ID4,ID2]`
+====
+
+
+==== Usage as Re-Ranking Query
+The `knn` query parser can be used to rerank first pass query results:
+[source,text]
+&q=id:(3 4 9 2)&rq={!rerank reRankQuery=$rqq reRankDocs=4 reRankWeight=1}&rqq={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]
+
+[IMPORTANT]
+====
+When using `knn` in reranking pay attention to the `topK` parameter.

Review comment:
       uniformed to "re-ranking", as it is used widely around Solr doc, thanks!




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] joel-bernstein commented on a change in pull request #476: SOLR-15880

Posted by GitBox <gi...@apache.org>.
joel-bernstein commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r786285685



##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,322 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.

Review comment:
       I'll add a link and a section to machine-learning.adoc showing how to integrate with math expressions. This is is now the key machine learning feature in Solr and its fits quite nicely with streaming expressions and math expressions. I'll add the docs after the patch lands.




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880: K Nearest Neighbors Search

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r787644328



##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not be solved simply by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+
+=== DenseVectorField
+The Dense Vector field gives the possibility of indexing and searching dense vectors of float elements.
+
+e.g.
+
+`[1.0, 2.5, 3.7, 4.1]` (array of float elements)
+
+Here's how `DenseVectorField` should be configured in the schema:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`vectorDimension`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The dimension of the dense vector to pass in.
++
+Accepted values:
+Integer < = 1024.
+
+`similarityFunction`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `euclidean`
+|===
++
+Vector similarity function; used in search to return top K most similar vectors to a target vector.
++
+Accepted values: `euclidean`, `dot_product`  or `cosine`.
+
+* `euclidean`: https://en.wikipedia.org/wiki/Euclidean_distance[Euclidean distance]
+* `dot_product`: https://en.wikipedia.org/wiki/Dot_product[Dot product]. *NOTE*: this similarity is intended as an optimized way to perform cosine similarity. In order to use it, all vectors must be of unit length, including both document and query vectors. Using dot product with vectors that are not unit length can result in errors or poor search results..
+* `cosine`: https://en.wikipedia.org/wiki/Cosine_similarity[Cosine similarity]. *NOTE*: the preferred way to perform cosine similarity is to normalize all vectors to unit length, and instead use DOT_PRODUCT. You should only use this function if you need to preserve the original vectors and cannot normalize them in advance.
+
+*N.B.* To use the following advanced parameters that customise the codec format
+and the hyper-parameter of the HNSW algorithm make sure you set this configuration in the solrconfig.xml:

Review comment:
       Thanks!




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880: K Nearest Neighbors Search

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r787651245



##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not be solved simply by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+
+=== DenseVectorField
+The Dense Vector field gives the possibility of indexing and searching dense vectors of float elements.
+
+e.g.
+
+`[1.0, 2.5, 3.7, 4.1]` (array of float elements)
+
+Here's how `DenseVectorField` should be configured in the schema:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`vectorDimension`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The dimension of the dense vector to pass in.
++
+Accepted values:
+Integer < = 1024.
+
+`similarityFunction`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `euclidean`
+|===
++
+Vector similarity function; used in search to return top K most similar vectors to a target vector.
++
+Accepted values: `euclidean`, `dot_product`  or `cosine`.
+
+* `euclidean`: https://en.wikipedia.org/wiki/Euclidean_distance[Euclidean distance]
+* `dot_product`: https://en.wikipedia.org/wiki/Dot_product[Dot product]. *NOTE*: this similarity is intended as an optimized way to perform cosine similarity. In order to use it, all vectors must be of unit length, including both document and query vectors. Using dot product with vectors that are not unit length can result in errors or poor search results..
+* `cosine`: https://en.wikipedia.org/wiki/Cosine_similarity[Cosine similarity]. *NOTE*: the preferred way to perform cosine similarity is to normalize all vectors to unit length, and instead use DOT_PRODUCT. You should only use this function if you need to preserve the original vectors and cannot normalize them in advance.
+
+*N.B.* To use the following advanced parameters that customise the codec format
+and the hyper-parameter of the HNSW algorithm make sure you set this configuration in the solrconfig.xml:
+[source,xml]
+<config>
+<codecFactory class="solr.SchemaCodecFactory"/>
+...
+
+Here's how `DenseVectorField` can be configured with the advanced codec hyper-parameters:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine" codecFormat="Lucene90HnswVectorsFormat" hnswMaxConnections="10" hnswBeamWidth="40"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`codecFormat`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `Lucene90HnswVectorsFormat`
+|===
++
+(advanced) Specifies the knn codec implementation to use
++
+
+Accepted values: `Lucene90HnswVectorsFormat`.
+
+Please note that the `codecFormat` accepted values may change in future releases.
+
+
+
+[NOTE]
+Lucene index back-compatibility is only supported for the default codec.
+If you choose to customize the `codecFormat` in your schema, upgrading to a future version of Solr may require you to either switch back to the default codec and optimize your index to rewrite it into the default codec before upgrading, or re-build your entire index from scratch after upgrading.
+
+`hnswMaxConnections`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 16
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+Controls how many of the nearest neighbor candidates are connected to the new node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++

Review comment:
       Agrred! Done

##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not be solved simply by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+
+=== DenseVectorField
+The Dense Vector field gives the possibility of indexing and searching dense vectors of float elements.
+
+e.g.
+
+`[1.0, 2.5, 3.7, 4.1]` (array of float elements)
+
+Here's how `DenseVectorField` should be configured in the schema:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`vectorDimension`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The dimension of the dense vector to pass in.
++
+Accepted values:
+Integer < = 1024.
+
+`similarityFunction`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `euclidean`
+|===
++
+Vector similarity function; used in search to return top K most similar vectors to a target vector.
++
+Accepted values: `euclidean`, `dot_product`  or `cosine`.
+
+* `euclidean`: https://en.wikipedia.org/wiki/Euclidean_distance[Euclidean distance]
+* `dot_product`: https://en.wikipedia.org/wiki/Dot_product[Dot product]. *NOTE*: this similarity is intended as an optimized way to perform cosine similarity. In order to use it, all vectors must be of unit length, including both document and query vectors. Using dot product with vectors that are not unit length can result in errors or poor search results..
+* `cosine`: https://en.wikipedia.org/wiki/Cosine_similarity[Cosine similarity]. *NOTE*: the preferred way to perform cosine similarity is to normalize all vectors to unit length, and instead use DOT_PRODUCT. You should only use this function if you need to preserve the original vectors and cannot normalize them in advance.
+
+*N.B.* To use the following advanced parameters that customise the codec format
+and the hyper-parameter of the HNSW algorithm make sure you set this configuration in the solrconfig.xml:
+[source,xml]
+<config>
+<codecFactory class="solr.SchemaCodecFactory"/>
+...
+
+Here's how `DenseVectorField` can be configured with the advanced codec hyper-parameters:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine" codecFormat="Lucene90HnswVectorsFormat" hnswMaxConnections="10" hnswBeamWidth="40"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`codecFormat`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `Lucene90HnswVectorsFormat`
+|===
++
+(advanced) Specifies the knn codec implementation to use
++
+
+Accepted values: `Lucene90HnswVectorsFormat`.
+
+Please note that the `codecFormat` accepted values may change in future releases.
+
+
+
+[NOTE]
+Lucene index back-compatibility is only supported for the default codec.
+If you choose to customize the `codecFormat` in your schema, upgrading to a future version of Solr may require you to either switch back to the default codec and optimize your index to rewrite it into the default codec before upgrading, or re-build your entire index from scratch after upgrading.
+
+`hnswMaxConnections`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 16
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+Controls how many of the nearest neighbor candidates are connected to the new node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++

Review comment:
       Agreed! Done




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880: K Nearest Neighbors Search

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r787654072



##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not be solved simply by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+
+=== DenseVectorField
+The Dense Vector field gives the possibility of indexing and searching dense vectors of float elements.
+
+e.g.
+
+`[1.0, 2.5, 3.7, 4.1]` (array of float elements)
+
+Here's how `DenseVectorField` should be configured in the schema:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`vectorDimension`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The dimension of the dense vector to pass in.
++
+Accepted values:
+Integer < = 1024.
+
+`similarityFunction`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `euclidean`
+|===
++
+Vector similarity function; used in search to return top K most similar vectors to a target vector.
++
+Accepted values: `euclidean`, `dot_product`  or `cosine`.
+
+* `euclidean`: https://en.wikipedia.org/wiki/Euclidean_distance[Euclidean distance]
+* `dot_product`: https://en.wikipedia.org/wiki/Dot_product[Dot product]. *NOTE*: this similarity is intended as an optimized way to perform cosine similarity. In order to use it, all vectors must be of unit length, including both document and query vectors. Using dot product with vectors that are not unit length can result in errors or poor search results..
+* `cosine`: https://en.wikipedia.org/wiki/Cosine_similarity[Cosine similarity]. *NOTE*: the preferred way to perform cosine similarity is to normalize all vectors to unit length, and instead use DOT_PRODUCT. You should only use this function if you need to preserve the original vectors and cannot normalize them in advance.
+
+*N.B.* To use the following advanced parameters that customise the codec format
+and the hyper-parameter of the HNSW algorithm make sure you set this configuration in the solrconfig.xml:
+[source,xml]
+<config>
+<codecFactory class="solr.SchemaCodecFactory"/>
+...
+
+Here's how `DenseVectorField` can be configured with the advanced codec hyper-parameters:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine" codecFormat="Lucene90HnswVectorsFormat" hnswMaxConnections="10" hnswBeamWidth="40"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`codecFormat`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `Lucene90HnswVectorsFormat`
+|===
++
+(advanced) Specifies the knn codec implementation to use
++
+
+Accepted values: `Lucene90HnswVectorsFormat`.
+
+Please note that the `codecFormat` accepted values may change in future releases.
+
+
+
+[NOTE]
+Lucene index back-compatibility is only supported for the default codec.
+If you choose to customize the `codecFormat` in your schema, upgrading to a future version of Solr may require you to either switch back to the default codec and optimize your index to rewrite it into the default codec before upgrading, or re-build your entire index from scratch after upgrading.
+
+`hnswMaxConnections`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 16
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+Controls how many of the nearest neighbor candidates are connected to the new node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `M` from the later paper.
++
+Accepted values:
+Integer.
+
+`hnswBeamWidth`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 100
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+It is the number of nearest neighbor candidates to track while searching the graph for each newly inserted node.
++

Review comment:
       as commented before, I would prefer to keep the explicit codec reference.
   Do you think it's a blocker?




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880: K Nearest Neighbors Search

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r787654429



##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not be solved simply by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+
+=== DenseVectorField
+The Dense Vector field gives the possibility of indexing and searching dense vectors of float elements.
+
+e.g.
+
+`[1.0, 2.5, 3.7, 4.1]` (array of float elements)
+
+Here's how `DenseVectorField` should be configured in the schema:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`vectorDimension`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The dimension of the dense vector to pass in.
++
+Accepted values:
+Integer < = 1024.
+
+`similarityFunction`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `euclidean`
+|===
++
+Vector similarity function; used in search to return top K most similar vectors to a target vector.
++
+Accepted values: `euclidean`, `dot_product`  or `cosine`.
+
+* `euclidean`: https://en.wikipedia.org/wiki/Euclidean_distance[Euclidean distance]
+* `dot_product`: https://en.wikipedia.org/wiki/Dot_product[Dot product]. *NOTE*: this similarity is intended as an optimized way to perform cosine similarity. In order to use it, all vectors must be of unit length, including both document and query vectors. Using dot product with vectors that are not unit length can result in errors or poor search results..
+* `cosine`: https://en.wikipedia.org/wiki/Cosine_similarity[Cosine similarity]. *NOTE*: the preferred way to perform cosine similarity is to normalize all vectors to unit length, and instead use DOT_PRODUCT. You should only use this function if you need to preserve the original vectors and cannot normalize them in advance.
+
+*N.B.* To use the following advanced parameters that customise the codec format
+and the hyper-parameter of the HNSW algorithm make sure you set this configuration in the solrconfig.xml:
+[source,xml]
+<config>
+<codecFactory class="solr.SchemaCodecFactory"/>
+...
+
+Here's how `DenseVectorField` can be configured with the advanced codec hyper-parameters:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine" codecFormat="Lucene90HnswVectorsFormat" hnswMaxConnections="10" hnswBeamWidth="40"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`codecFormat`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `Lucene90HnswVectorsFormat`
+|===
++
+(advanced) Specifies the knn codec implementation to use
++
+
+Accepted values: `Lucene90HnswVectorsFormat`.
+
+Please note that the `codecFormat` accepted values may change in future releases.
+
+
+
+[NOTE]
+Lucene index back-compatibility is only supported for the default codec.
+If you choose to customize the `codecFormat` in your schema, upgrading to a future version of Solr may require you to either switch back to the default codec and optimize your index to rewrite it into the default codec before upgrading, or re-build your entire index from scratch after upgrading.
+
+`hnswMaxConnections`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 16
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+Controls how many of the nearest neighbor candidates are connected to the new node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `M` from the later paper.
++
+Accepted values:
+Integer.
+
+`hnswBeamWidth`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 100
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+It is the number of nearest neighbor candidates to track while searching the graph for each newly inserted node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++

Review comment:
       Removed!




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r786728212



##########
File path: solr/core/src/java/org/apache/solr/schema/DenseVectorField.java
##########
@@ -0,0 +1,256 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.solr.schema;
+
+import org.apache.lucene.codecs.lucene90.Lucene90HnswVectorsFormat;
+import org.apache.lucene.document.KnnVectorField;
+import org.apache.lucene.index.IndexableField;
+import org.apache.lucene.index.VectorSimilarityFunction;
+import org.apache.lucene.queries.function.ValueSource;
+import org.apache.lucene.search.KnnVectorQuery;
+import org.apache.lucene.search.Query;
+import org.apache.lucene.search.SortField;
+import org.apache.lucene.util.hnsw.HnswGraph;
+import org.apache.solr.common.SolrException;
+import org.apache.solr.search.QParser;
+import org.apache.solr.uninverting.UninvertingReader;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
+
+import static java.util.Optional.ofNullable;
+import static org.apache.lucene.codecs.lucene90.Lucene90HnswVectorsFormat.DEFAULT_BEAM_WIDTH;
+import static org.apache.lucene.codecs.lucene90.Lucene90HnswVectorsFormat.DEFAULT_MAX_CONN;
+
+/**
+ * Provides a field type to support Lucene's {@link
+ * org.apache.lucene.document.KnnVectorField}.
+ * See {@link org.apache.lucene.search.KnnVectorQuery} for more details.
+ * It supports a fixed cardinality dimension for the vector and a fixed similarity function.
+ * The default similarity is EUCLIDEAN_HNSW (L2).
+ * The default index codec format is specified in the Lucene Codec constructor.
+ * For Lucene 9.0 e.g.
+ * See {@link org.apache.lucene.codecs.lucene90.Lucene90Codec}
+ * Currently only {@link org.apache.lucene.codecs.lucene90.Lucene90HnswVectorsFormat} is supported for
+ * advanced hyper-parameter customisation.
+ * See {@link org.apache.lucene.util.hnsw.HnswGraph} for more details about the implementation. 
+ *
+ * <br>
+ * Only {@code Indexed} and {@code Stored} attributes are supported.
+ */
+public class DenseVectorField extends FloatPointField {
+
+    static final String KNN_VECTOR_DIMENSION = "vectorDimension";
+    static final String KNN_SIMILARITY_FUNCTION = "similarityFunction";
+    
+    static final String CODEC_FORMAT = "codecFormat";
+    static final String HNSW_MAX_CONNECTIONS = "hnswMaxConnections";
+    static final String HNSW_BEAM_WIDTH = "hnswBeamWidth";
+
+    int dimension;
+    VectorSimilarityFunction similarityFunction;
+    VectorSimilarityFunction DEFAULT_SIMILARITY = VectorSimilarityFunction.EUCLIDEAN;
+
+    String codecFormat;
+    /**
+     * This parameter is coupled with the {@link Lucene90HnswVectorsFormat} format implementation.
+     * Controls how many of the nearest neighbor candidates are connected to the new node. Defaults to
+     * {@link Lucene90HnswVectorsFormat#DEFAULT_MAX_CONN}. See {@link HnswGraph} for more details.
+     */
+    int hnswMaxConn;
+    /**
+     * This parameter is coupled with the {@link Lucene90HnswVectorsFormat} format implementation.
+     * The number of candidate neighbors to track while searching the graph for each newly inserted
+     * node. Defaults to to {@link Lucene90HnswVectorsFormat#DEFAULT_BEAM_WIDTH}. See {@link
+     * HnswGraph} for details.
+     */
+    int hnswBeamWidth;
+
+    @Override
+    public void init(IndexSchema schema, Map<String, String> args) {
+        this.dimension = ofNullable(args.get(KNN_VECTOR_DIMENSION))
+                .map(value -> Integer.parseInt(value))
+                .orElseThrow(() -> new SolrException(SolrException.ErrorCode.SERVER_ERROR, "the vector dimension is a mandatory parameter"));
+        args.remove(KNN_VECTOR_DIMENSION);
+
+        this.similarityFunction = ofNullable(args.get(KNN_SIMILARITY_FUNCTION))
+                .map(value -> VectorSimilarityFunction.valueOf(value.toUpperCase(Locale.ROOT)))
+                .orElse(DEFAULT_SIMILARITY);
+        args.remove(KNN_SIMILARITY_FUNCTION);
+
+        this.codecFormat = args.get(CODEC_FORMAT);
+        args.remove(CODEC_FORMAT);
+
+        this.hnswMaxConn = ofNullable(args.get(HNSW_MAX_CONNECTIONS))
+                .map(value -> Integer.parseInt(value))
+                .orElse(DEFAULT_MAX_CONN);
+        args.remove(HNSW_MAX_CONNECTIONS);
+
+        this.hnswBeamWidth = ofNullable(args.get(HNSW_BEAM_WIDTH))
+                .map(value -> Integer.parseInt(value))
+                .orElse(DEFAULT_BEAM_WIDTH);
+        args.remove(HNSW_BEAM_WIDTH);
+
+        this.properties &= ~MULTIVALUED;
+        this.properties &= ~UNINVERTIBLE;
+        
+        super.init(schema, args);
+    }
+
+    public int getDimension() {
+        return dimension;
+    }
+
+    public String getCodecFormat() {
+        return codecFormat;
+    }
+
+    public Integer getHnswMaxConn() {
+        return hnswMaxConn;
+    }
+
+    public Integer getHnswBeamWidth() {
+        return hnswBeamWidth;
+    }
+
+    @Override
+    public void checkSchemaField(final SchemaField field) throws SolrException {
+        super.checkSchemaField(field);
+        if (field.multiValued()) {
+            throw new SolrException(SolrException.ErrorCode.SERVER_ERROR,
+                    getClass().getSimpleName() + " fields can not be multiValued: " + field.getName());
+        }
+
+        if (field.hasDocValues()) {
+            throw new SolrException(SolrException.ErrorCode.SERVER_ERROR,
+                    getClass().getSimpleName() + " fields can not have docValues: " + field.getName());
+        }
+    }
+    
+    public List<IndexableField> createFields(SchemaField field, Object value) {
+        List<IndexableField> fields = new ArrayList<>();
+        float[] parsedVector;
+        try {
+            parsedVector = parseVector(value);
+        } catch (RuntimeException e) {
+            throw new SolrException(SolrException.ErrorCode.SERVER_ERROR, "Error while creating field '" + field + "' from value '" + value + "', expected format:'[f1, f2, f3...fn]' e.g. [1.0, 3.4, 5.6]", e);
+        }
+

Review comment:
       That's a good idea to reduce the arraylist resizes!
   I've done with:
   
   if (field.stored()) {
               fields.ensureCapacity(parsedVector.length + 1);
               for (float vectorElement : parsedVector) {
                   fields.add(getStoredField(field, vectorElement));
               }
           }
           
           Thanks!




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r781086367



##########
File path: solr/core/src/java/org/apache/solr/search/neural/KnnQParser.java
##########
@@ -0,0 +1,100 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.solr.search.neural;
+
+import org.apache.lucene.search.Query;
+import org.apache.solr.common.SolrException;
+import org.apache.solr.common.params.SolrParams;
+import org.apache.solr.request.SolrQueryRequest;
+import org.apache.solr.schema.DenseVectorField;
+import org.apache.solr.schema.FieldType;
+import org.apache.solr.schema.SchemaField;
+import org.apache.solr.search.QParser;
+import org.apache.solr.search.QueryParsing;
+
+public class KnnQParser extends QParser {
+
+    static final String TOP_K = "topK";// retrieve the top K results based on the distance similarity function 
+    static final int DEFAULT_TOP_K = 10;
+
+    /**
+     * Constructor for the QParser
+     *
+     * @param qstr        The part of the query string specific to this parser
+     * @param localParams The set of parameters that are specific to this QParser.  See https://solr.apache.org/guide/local-parameters-in-queries.html
+     * @param params      The rest of the {@link SolrParams}
+     * @param req         The original {@link SolrQueryRequest}.
+     */
+    public KnnQParser(String qstr, SolrParams localParams, SolrParams params, SolrQueryRequest req) {
+        super(qstr, localParams, params, req);
+    }
+
+    @Override
+    public Query parse() {
+        String denseVectorField = localParams.get(QueryParsing.F);
+        String vectorToSearch = localParams.get(QueryParsing.V);
+        int topK = localParams.getInt(TOP_K, DEFAULT_TOP_K);
+
+        if (denseVectorField == null || denseVectorField.isEmpty()) {
+            throw new SolrException(SolrException.ErrorCode.BAD_REQUEST, "the Dense Vector field 'f' is missing");
+        }
+
+        if (vectorToSearch == null || vectorToSearch.isEmpty()) {
+            throw new SolrException(SolrException.ErrorCode.BAD_REQUEST, "the Dense Vector to search is missing");
+        }
+
+        SchemaField schemaField = req.getCore().getLatestSchema().getField(denseVectorField);
+        FieldType fieldType = schemaField.getType();
+        if (!(fieldType instanceof DenseVectorField)) {
+            throw new SolrException(SolrException.ErrorCode.BAD_REQUEST, "only DenseVectorField is compatible with Knn Query Parser");
+        }
+
+        DenseVectorField denseVectorType = (DenseVectorField) fieldType;
+        float[] parsedVectorToSearch = parseVector(vectorToSearch, denseVectorType.getDimension());
+        return denseVectorType.getKnnVectorQuery(schemaField, parsedVectorToSearch, topK);
+    }
+
+    /**
+     * Parses a String vector.
+     *
+     * @param value with format: [f1, f2, f3, f4...fn]
+     * @return a float array
+     */
+    private float[] parseVector(String value, int dimension) {
+        if (!value.startsWith("[") || !value.endsWith("]")) {
+            throw new SolrException(SolrException.ErrorCode.BAD_REQUEST, "incorrect vector format." +
+                    " The expected format is:'[f1,f2..f3]' where each element f is a float");
+        }
+
+        String[] elements = value.substring(1, value.length() - 1).split(",");

Review comment:
       Thanks for the suggestion, done!




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r783010421



##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,320 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+With the *Neural Search* module Apache Solr is introducing support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not simply be solved by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+
+=== DenseVectorField
+The Dense Vector field gives the possibility of indexing and searching dense vectors of float elements.
+
+e.g.
+
+`[1.0, 2.5, 3.7, 4.1]` (array of float elements)
+
+Here's how `DenseVectorField` should be configured in the schema:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`vectorDimension`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The dimension of the dense vector to pass in.
++
+Accepted values:
+Integer < = 1024.
+
+`similarityFunction`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `euclidean`
+|===
++
+Vector similarity function; used in search to return top K most similar vectors to a target vector.
++
+Accepted values: `euclidean`, `dot_product`  or `cosine`.
+
+* `euclidean`: https://en.wikipedia.org/wiki/Euclidean_distance[Euclidean distance]
+* `dot_product`: https://en.wikipedia.org/wiki/Dot_product[Dot product]. *NOTE*: this similarity is intended as an optimized way to perform cosine similarity. In order to use it, all vectors must be of unit length, including both document and query vectors. Using dot product with vectors that are not unit length can result in errors or poor search results..
+* `cosine`: https://en.wikipedia.org/wiki/Cosine_similarity[Cosine similarity]. *NOTE*: the preferred way to perform cosine similarity is to normalize all vectors to unit length, and instead use DOT_PRODUCT. You should only use this function if you need to preserve the original vectors and cannot normalize them in advance.
+
+*N.B.* To use the following advanced parameters that customise the codec format
+and the hyper-parameter of the HNSW algorithm make sure you set this configuration in the solrconfig.xml:
+[source,xml]
+<config>
+<codecFactory class="solr.SchemaCodecFactory"/>
+...
+
+Here's how `DenseVectorField` can be configured with the advanced codec hyper-parameters:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine" codecFormat="Lucene90HnswVectorsFormat" hnswMaxConnections="10" hnswBeamWidth="40"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`codecFormat`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `Lucene90HnswVectorsFormat`
+|===
++
+(advanced) Specifies the knn codec implementation to use
++
+
+Accepted values: `Lucene90HnswVectorsFormat`.
+
+Please note that the `codecFormat` accepted values may change in future releases.
+
+
+
+[NOTE]
+Lucene index back-compatibility is only supported for the default codec.
+If you choose to customize the `codecFormat` in your schema, upgrading to a future version of Solr may require you to either switch back to the default codec and optimize your index to rewrite it into the default codec before upgrading, or re-build your entire index from scratch after upgrading.
+
+`hnswMaxConnections`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 16
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+Controls how many of the nearest neighbor candidates are connected to the new node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `M` from the later paper.
++
+Accepted values:
+Integer.
+
+`hnswBeamWidth`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 100
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+It is the number of nearest neighbor candidates to track while searching the graph for each newly inserted node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `efConstruction` from the later paper.
++
+Accepted values:
+Integer.
+
+DenseVectorField supports the attributes: `indexed`, `stored`.
+
+*N.B.* currently multivalue is not supported
+
+Here's how a `DenseVectorField` should be indexed:
+
+[.dynamic-tabs]
+--
+[example.tab-pane#json]
+====
+[.tab-label]*JSON*
+[source,json]
+----
+[{ "id": "1",
+"vector": [1.0, 2.5, 3.7, 4.1]
+},
+{ "id": "2",
+"vector": [1.5, 5.5, 6.7, 65.1]
+}
+]
+----
+====
+
+[example.tab-pane#xml]
+====
+[.tab-label]*XML*
+[source,xml]
+----
+<add>
+<doc>
+<field name="id">1</field>
+<field name="vector">1.0</field>
+<field name="vector">2.5</field>
+<field name="vector">3.7</field>
+<field name="vector">4.1</field>
+</doc>
+<doc>
+<field name="id">2</field>
+<field name="vector">1.5</field>
+<field name="vector">5.5</field>
+<field name="vector">6.7</field>
+<field name="vector">65.1</field>
+</doc>
+</add>
+----
+====
+
+[example.tab-pane#solrj]
+====
+[.tab-label]*SolrJ*
+[source,java,indent=0]
+----
+final SolrClient client = getSolrClient();
+
+final SolrInputDocument d1 = new SolrInputDocument();
+d1.setField("id", "1");
+d1.setField("vector", Arrays.asList(1.0f, 2.5f, 3.7f, 4.1f));
+
+
+final SolrInputDocument d2 = new SolrInputDocument();
+d2.setField("id", "2");
+d2.setField("vector", Arrays.asList(1.5f, 5.5f, 6.7f, 65.1f));
+
+client.add(Arrays.asList(d1, d2));
+----
+====
+--
+
+== Query Time
+This is the list of Apache Solr query approaches designed to support Neural Search:
+
+=== knn Query Parser
+The `knn` K-Nearest Neighbors query parser allows to find the k-nearest documents to the target vector according to indexed dense vectors in the given field.
+
+It takes the following parameters:
+
+`f`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The DenseVectorField to search in.
+
+`topK`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 10
+|===
++
+How many k-nearest results to return.
+
+Here's how to run a KNN search:
+
+[source,text]
+&q={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]
+
+The search results retrieved are the K-nearest to the vector in input `[1.0, 2.0, 3.0, 4.0]`, ranked by the similarityFunction configured at indexing time.
+
+==== Usage with Filter Queries
+The `knn` query parser can be used in filter queries:
+[source,text]
+&q=id:(1 2 3)&fq={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]
+
+The `knn` query parser can be used with filter queries:
+[source,text]
+&q={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]&fq=id:(1 2 3)
+
+[IMPORTANT]
+====
+When using `knn` in these scenarios make sure you have clear how filter queries work in Apache Solr:
+
+The Ranked List of document IDs resulting from the main query `q` is intersected with the set of document IDs deriving from each filter query `fq`.
+
+e.g.
+
+Ranked List from `q`=`[ID1, ID4, ID2, ID10]` <intersects> Set from `fq`=`{ID3, ID2, ID9, ID4}` = `[ID4,ID2]`
+====
+
+
+==== Usage as Re-Ranking Query
+The `knn` query parser can be used to rerank first pass query results:
+[source,text]
+&q=id:(3 4 9 2)&rq={!rerank reRankQuery=$rqq reRankDocs=4 reRankWeight=1}&rqq={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]
+
+[IMPORTANT]
+====
+When using `knn` in reranking pay attention to the `topK` parameter.
+
+The second pass score(deriving from knn) is calculated only if the documend `d` from the first pass is within
+the K-nearest neighbors(*in the whole index*) of the target vector to search.
+
+This means the second pass `knn` is executed on the whole index anyway, which is a current limitation.

Review comment:
       No Jira yet, but it's one of my top priority to create, together with the multivalue support!




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r783023972



##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,320 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+With the *Neural Search* module Apache Solr is introducing support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not simply be solved by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+
+=== DenseVectorField
+The Dense Vector field gives the possibility of indexing and searching dense vectors of float elements.
+
+e.g.
+
+`[1.0, 2.5, 3.7, 4.1]` (array of float elements)
+
+Here's how `DenseVectorField` should be configured in the schema:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`vectorDimension`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The dimension of the dense vector to pass in.
++
+Accepted values:
+Integer < = 1024.
+
+`similarityFunction`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `euclidean`
+|===
++
+Vector similarity function; used in search to return top K most similar vectors to a target vector.
++
+Accepted values: `euclidean`, `dot_product`  or `cosine`.
+
+* `euclidean`: https://en.wikipedia.org/wiki/Euclidean_distance[Euclidean distance]
+* `dot_product`: https://en.wikipedia.org/wiki/Dot_product[Dot product]. *NOTE*: this similarity is intended as an optimized way to perform cosine similarity. In order to use it, all vectors must be of unit length, including both document and query vectors. Using dot product with vectors that are not unit length can result in errors or poor search results..
+* `cosine`: https://en.wikipedia.org/wiki/Cosine_similarity[Cosine similarity]. *NOTE*: the preferred way to perform cosine similarity is to normalize all vectors to unit length, and instead use DOT_PRODUCT. You should only use this function if you need to preserve the original vectors and cannot normalize them in advance.
+
+*N.B.* To use the following advanced parameters that customise the codec format
+and the hyper-parameter of the HNSW algorithm make sure you set this configuration in the solrconfig.xml:
+[source,xml]
+<config>
+<codecFactory class="solr.SchemaCodecFactory"/>
+...
+
+Here's how `DenseVectorField` can be configured with the advanced codec hyper-parameters:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine" codecFormat="Lucene90HnswVectorsFormat" hnswMaxConnections="10" hnswBeamWidth="40"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`codecFormat`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `Lucene90HnswVectorsFormat`
+|===
++
+(advanced) Specifies the knn codec implementation to use
++
+
+Accepted values: `Lucene90HnswVectorsFormat`.
+
+Please note that the `codecFormat` accepted values may change in future releases.
+
+
+
+[NOTE]
+Lucene index back-compatibility is only supported for the default codec.
+If you choose to customize the `codecFormat` in your schema, upgrading to a future version of Solr may require you to either switch back to the default codec and optimize your index to rewrite it into the default codec before upgrading, or re-build your entire index from scratch after upgrading.
+
+`hnswMaxConnections`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 16
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+Controls how many of the nearest neighbor candidates are connected to the new node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `M` from the later paper.
++
+Accepted values:
+Integer.
+
+`hnswBeamWidth`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 100
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+It is the number of nearest neighbor candidates to track while searching the graph for each newly inserted node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `efConstruction` from the later paper.
++
+Accepted values:
+Integer.
+
+DenseVectorField supports the attributes: `indexed`, `stored`.
+
+*N.B.* currently multivalue is not supported
+
+Here's how a `DenseVectorField` should be indexed:
+
+[.dynamic-tabs]
+--
+[example.tab-pane#json]
+====
+[.tab-label]*JSON*
+[source,json]
+----
+[{ "id": "1",
+"vector": [1.0, 2.5, 3.7, 4.1]
+},
+{ "id": "2",
+"vector": [1.5, 5.5, 6.7, 65.1]
+}
+]
+----
+====
+
+[example.tab-pane#xml]
+====
+[.tab-label]*XML*
+[source,xml]
+----
+<add>
+<doc>
+<field name="id">1</field>
+<field name="vector">1.0</field>
+<field name="vector">2.5</field>
+<field name="vector">3.7</field>
+<field name="vector">4.1</field>
+</doc>
+<doc>
+<field name="id">2</field>
+<field name="vector">1.5</field>
+<field name="vector">5.5</field>
+<field name="vector">6.7</field>
+<field name="vector">65.1</field>
+</doc>
+</add>
+----
+====
+
+[example.tab-pane#solrj]
+====
+[.tab-label]*SolrJ*
+[source,java,indent=0]
+----
+final SolrClient client = getSolrClient();
+
+final SolrInputDocument d1 = new SolrInputDocument();
+d1.setField("id", "1");
+d1.setField("vector", Arrays.asList(1.0f, 2.5f, 3.7f, 4.1f));
+
+
+final SolrInputDocument d2 = new SolrInputDocument();
+d2.setField("id", "2");
+d2.setField("vector", Arrays.asList(1.5f, 5.5f, 6.7f, 65.1f));
+
+client.add(Arrays.asList(d1, d2));
+----
+====
+--
+
+== Query Time
+This is the list of Apache Solr query approaches designed to support Neural Search:
+
+=== knn Query Parser
+The `knn` K-Nearest Neighbors query parser allows to find the k-nearest documents to the target vector according to indexed dense vectors in the given field.
+
+It takes the following parameters:
+
+`f`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The DenseVectorField to search in.
+
+`topK`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 10
+|===
++
+How many k-nearest results to return.
+
+Here's how to run a KNN search:
+
+[source,text]
+&q={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]
+
+The search results retrieved are the K-nearest to the vector in input `[1.0, 2.0, 3.0, 4.0]`, ranked by the similarityFunction configured at indexing time.
+
+==== Usage with Filter Queries
+The `knn` query parser can be used in filter queries:
+[source,text]
+&q=id:(1 2 3)&fq={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]
+
+The `knn` query parser can be used with filter queries:
+[source,text]
+&q={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]&fq=id:(1 2 3)
+
+[IMPORTANT]
+====
+When using `knn` in these scenarios make sure you have clear how filter queries work in Apache Solr:
+
+The Ranked List of document IDs resulting from the main query `q` is intersected with the set of document IDs deriving from each filter query `fq`.
+
+e.g.
+
+Ranked List from `q`=`[ID1, ID4, ID2, ID10]` <intersects> Set from `fq`=`{ID3, ID2, ID9, ID4}` = `[ID4,ID2]`
+====
+
+
+==== Usage as Re-Ranking Query
+The `knn` query parser can be used to rerank first pass query results:
+[source,text]
+&q=id:(3 4 9 2)&rq={!rerank reRankQuery=$rqq reRankDocs=4 reRankWeight=1}&rqq={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]
+
+[IMPORTANT]
+====
+When using `knn` in reranking pay attention to the `topK` parameter.
+
+The second pass score(deriving from knn) is calculated only if the documend `d` from the first pass is within
+the K-nearest neighbors(*in the whole index*) of the target vector to search.
+
+This means the second pass `knn` is executed on the whole index anyway, which is a current limitation.
+
+The final ranked list of results will have the first pass score(main query `q`) combined with the second pass score(the approximated similarityFunction distance to the target vector to search).
+====
+
+== Additional Neural Search Resources
+
+* Apache Solr Dense Vectors

Review comment:
       We are working on them, almost finished.
   Assuming a release in 9.1 they will be fully functioning and adding info, guidance and benchmarks :)




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on pull request #476: SOLR-15880

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on pull request #476:
URL: https://github.com/apache/solr/pull/476#issuecomment-1003079734


   Done another iteration, with quite a good quantity of changes. Many issues related with the serialization/deserialization should be solved.
   I'll take a look after new year to the hyper-parameter mentioned by @msokolov !
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r783023194



##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,320 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+With the *Neural Search* module Apache Solr is introducing support for neural networks based techniques that can improve various aspects of search.

Review comment:
       I am not a native speaker, but is "With the *Neural Search* module Apache Solr is support for neural networks based techniques" correct? I didn't know of the construct:
   "with 'something' Apache Solr is support for 'something'
   




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r775053179



##########
File path: solr/core/src/java/org/apache/solr/schema/DenseVectorField.java
##########
@@ -0,0 +1,200 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.solr.schema;
+
+import org.apache.lucene.document.KnnVectorField;
+import org.apache.lucene.document.StoredField;
+import org.apache.lucene.index.IndexableField;
+import org.apache.lucene.index.VectorSimilarityFunction;
+import org.apache.lucene.queries.function.ValueSource;
+import org.apache.lucene.search.KnnVectorQuery;
+import org.apache.lucene.search.Query;
+import org.apache.lucene.search.SortField;
+import org.apache.solr.common.SolrException;
+import org.apache.solr.response.TextResponseWriter;
+import org.apache.solr.search.QParser;
+import org.apache.solr.uninverting.UninvertingReader;
+
+import java.io.IOException;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
+
+import static java.util.Optional.ofNullable;
+
+/**
+ * Provides a field type to support Lucene's {@link
+ * org.apache.lucene.document.KnnVectorField}.
+ * See {@link org.apache.lucene.search.KnnVectorQuery} for more details.
+ * It supports a fixed cardinality dimension for the vector and a fixed similarity function.
+ * The default similarity is EUCLIDEAN_HNSW (L2).
+ * See subclasses for details.
+ *
+ * <br>
+ * Only {@code Indexed} and {@code Stored} attributes are supported.
+ */
+public class DenseVectorField extends FieldType {
+
+    static final String KNN_VECTOR_DIMENSION = "vectorDimension";
+    static final String KNN_SIMILARITY_FUNCTION = "similarityFunction";
+    
+    int dimension;
+    VectorSimilarityFunction similarityFunction;
+    VectorSimilarityFunction DEFAULT_SIMILARITY = VectorSimilarityFunction.EUCLIDEAN;
+
+    @Override
+    public void init(IndexSchema schema, Map<String, String> args){
+        this.dimension = ofNullable(args.get(KNN_VECTOR_DIMENSION))
+                .map(value -> parseDimensionParameter(value))
+                .orElseThrow(() -> new SolrException(SolrException.ErrorCode.SERVER_ERROR, "the vector dimension is a mandatory parameter"));
+        args.remove(KNN_VECTOR_DIMENSION);
+
+        this.similarityFunction = ofNullable(args.get(KNN_SIMILARITY_FUNCTION))
+                .map(value -> VectorSimilarityFunction.valueOf(value.toUpperCase(Locale.ROOT)))
+                .orElse(DEFAULT_SIMILARITY);
+        args.remove(KNN_SIMILARITY_FUNCTION);
+
+        this.properties &= ~MULTIVALUED;
+        this.properties &= ~UNINVERTIBLE;
+        
+        super.init(schema, args);
+    }
+
+    private int parseDimensionParameter(String value) {
+        try {
+            return Integer.parseInt(value);
+        } catch (NumberFormatException e) {
+            throw new SolrException(SolrException.ErrorCode.SERVER_ERROR, "the vector dimension must be an integer");
+        }
+    }
+
+    @Override
+    public void checkSchemaField(final SchemaField field) throws SolrException {
+        super.checkSchemaField(field);
+        if (field.multiValued()) {
+            throw new SolrException(SolrException.ErrorCode.SERVER_ERROR,
+                    getClass().getSimpleName() + " fields can not be multiValued: " + field.getName());
+        }
+    }
+    
+    public List<IndexableField> createFields(SchemaField field, Object value) {
+        List<IndexableField> fields = new ArrayList<>();
+        if (field.indexed()){
+            fields.add(createField(field, value));
+        }
+        if (field.stored()){
+            fields.add(createStoredField(field, value));
+        }
+        return fields;
+    }
+
+    private IndexableField createStoredField(SchemaField field, Object value) {
+        return new StoredField(field.getName(), value.toString());
+    }
+
+    @Override
+    public UninvertingReader.Type getUninversionType(SchemaField sf) {
+        return null;
+    }
+
+    @Override
+    public ValueSource getValueSource(SchemaField field, QParser parser) {
+        throw new SolrException(SolrException.ErrorCode.BAD_REQUEST,
+                "Function queries are not supported for Dense Vector fields.");
+    }
+
+    @Override
+    public void write(TextResponseWriter writer, String name, IndexableField f) throws IOException {
+        writer.writeVal(name, f.stringValue());
+    }
+
+    @Override
+    public IndexableField createField(SchemaField field, Object value) {
+        float[] parsedVector;
+        try {
+            parsedVector = parseVector(value.toString());
+        } catch (RuntimeException e) {
+            throw new SolrException(SolrException.ErrorCode.SERVER_ERROR, "Error while creating field '" + field + "' from value '" + value + "', expected format:'[f1, f2, f3...fn]' e.g. [1.0, 3.4, 5.6]", e);
+        }
+        if (parsedVector == null) return null;
+
+        return new KnnVectorField(field.getName(), parsedVector, similarityFunction);
+    }
+
+    /**
+     * Parses a String vector.
+     *
+     * @param value with format: [f1, f2, f3, f4...fn]
+     * @return a float array
+     */
+    private float[] parseVector(String value) {
+        if (!value.startsWith("[") || !value.endsWith("]")) {
+            throw new SolrException(SolrException.ErrorCode.BAD_REQUEST, "incorrect vector format." +
+                    " The expected format is:'[f1,f2..f3]' where each element f is a float");
+        }
+        
+        String[] elements = value.substring(1, value.length() - 1).split(",");

Review comment:
       I checked and the .split("regex") method is used hundreds of times in the Apache Solr codebase, unless any further observations I am resolving this comment.




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] msokolov commented on a change in pull request #476: SOLR-15880

Posted by GitBox <gi...@apache.org>.
msokolov commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r775498074



##########
File path: solr/core/src/java/org/apache/solr/schema/DenseVectorField.java
##########
@@ -0,0 +1,200 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.solr.schema;
+
+import org.apache.lucene.document.KnnVectorField;
+import org.apache.lucene.document.StoredField;
+import org.apache.lucene.index.IndexableField;
+import org.apache.lucene.index.VectorSimilarityFunction;
+import org.apache.lucene.queries.function.ValueSource;
+import org.apache.lucene.search.KnnVectorQuery;
+import org.apache.lucene.search.Query;
+import org.apache.lucene.search.SortField;
+import org.apache.solr.common.SolrException;
+import org.apache.solr.response.TextResponseWriter;
+import org.apache.solr.search.QParser;
+import org.apache.solr.uninverting.UninvertingReader;
+
+import java.io.IOException;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
+
+import static java.util.Optional.ofNullable;
+
+/**
+ * Provides a field type to support Lucene's {@link
+ * org.apache.lucene.document.KnnVectorField}.
+ * See {@link org.apache.lucene.search.KnnVectorQuery} for more details.
+ * It supports a fixed cardinality dimension for the vector and a fixed similarity function.
+ * The default similarity is EUCLIDEAN_HNSW (L2).
+ * See subclasses for details.
+ *
+ * <br>
+ * Only {@code Indexed} and {@code Stored} attributes are supported.
+ */
+public class DenseVectorField extends FieldType {
+
+    static final String KNN_VECTOR_DIMENSION = "vectorDimension";
+    static final String KNN_SIMILARITY_FUNCTION = "similarityFunction";
+    
+    int dimension;
+    VectorSimilarityFunction similarityFunction;
+    VectorSimilarityFunction DEFAULT_SIMILARITY = VectorSimilarityFunction.EUCLIDEAN;
+
+    @Override
+    public void init(IndexSchema schema, Map<String, String> args){
+        this.dimension = ofNullable(args.get(KNN_VECTOR_DIMENSION))
+                .map(value -> parseDimensionParameter(value))
+                .orElseThrow(() -> new SolrException(SolrException.ErrorCode.SERVER_ERROR, "the vector dimension is a mandatory parameter"));
+        args.remove(KNN_VECTOR_DIMENSION);
+
+        this.similarityFunction = ofNullable(args.get(KNN_SIMILARITY_FUNCTION))
+                .map(value -> VectorSimilarityFunction.valueOf(value.toUpperCase(Locale.ROOT)))
+                .orElse(DEFAULT_SIMILARITY);
+        args.remove(KNN_SIMILARITY_FUNCTION);
+
+        this.properties &= ~MULTIVALUED;
+        this.properties &= ~UNINVERTIBLE;
+        
+        super.init(schema, args);
+    }
+
+    private int parseDimensionParameter(String value) {
+        try {
+            return Integer.parseInt(value);
+        } catch (NumberFormatException e) {
+            throw new SolrException(SolrException.ErrorCode.SERVER_ERROR, "the vector dimension must be an integer");
+        }
+    }
+
+    @Override
+    public void checkSchemaField(final SchemaField field) throws SolrException {
+        super.checkSchemaField(field);
+        if (field.multiValued()) {
+            throw new SolrException(SolrException.ErrorCode.SERVER_ERROR,
+                    getClass().getSimpleName() + " fields can not be multiValued: " + field.getName());
+        }
+    }
+    
+    public List<IndexableField> createFields(SchemaField field, Object value) {
+        List<IndexableField> fields = new ArrayList<>();
+        if (field.indexed()){
+            fields.add(createField(field, value));
+        }
+        if (field.stored()){
+            fields.add(createStoredField(field, value));
+        }
+        return fields;
+    }
+
+    private IndexableField createStoredField(SchemaField field, Object value) {
+        return new StoredField(field.getName(), value.toString());

Review comment:
       This doesn't seem like something very useful for numeric vector fields? You'd end up with strings like `[0.3485723998437523,...]` which would be a very inefficient way to store the information

##########
File path: solr/core/src/java/org/apache/solr/schema/DenseVectorField.java
##########
@@ -0,0 +1,200 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.solr.schema;
+
+import org.apache.lucene.document.KnnVectorField;
+import org.apache.lucene.document.StoredField;
+import org.apache.lucene.index.IndexableField;
+import org.apache.lucene.index.VectorSimilarityFunction;
+import org.apache.lucene.queries.function.ValueSource;
+import org.apache.lucene.search.KnnVectorQuery;
+import org.apache.lucene.search.Query;
+import org.apache.lucene.search.SortField;
+import org.apache.solr.common.SolrException;
+import org.apache.solr.response.TextResponseWriter;
+import org.apache.solr.search.QParser;
+import org.apache.solr.uninverting.UninvertingReader;
+
+import java.io.IOException;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
+
+import static java.util.Optional.ofNullable;
+
+/**
+ * Provides a field type to support Lucene's {@link
+ * org.apache.lucene.document.KnnVectorField}.
+ * See {@link org.apache.lucene.search.KnnVectorQuery} for more details.
+ * It supports a fixed cardinality dimension for the vector and a fixed similarity function.
+ * The default similarity is EUCLIDEAN_HNSW (L2).

Review comment:
       Should we also document the other format(s) that are supported (DOT_PRODUCT)?

##########
File path: solr/core/src/java/org/apache/solr/schema/DenseVectorField.java
##########
@@ -0,0 +1,200 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.solr.schema;
+
+import org.apache.lucene.document.KnnVectorField;
+import org.apache.lucene.document.StoredField;
+import org.apache.lucene.index.IndexableField;
+import org.apache.lucene.index.VectorSimilarityFunction;
+import org.apache.lucene.queries.function.ValueSource;
+import org.apache.lucene.search.KnnVectorQuery;
+import org.apache.lucene.search.Query;
+import org.apache.lucene.search.SortField;
+import org.apache.solr.common.SolrException;
+import org.apache.solr.response.TextResponseWriter;
+import org.apache.solr.search.QParser;
+import org.apache.solr.uninverting.UninvertingReader;
+
+import java.io.IOException;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
+
+import static java.util.Optional.ofNullable;
+
+/**
+ * Provides a field type to support Lucene's {@link
+ * org.apache.lucene.document.KnnVectorField}.
+ * See {@link org.apache.lucene.search.KnnVectorQuery} for more details.
+ * It supports a fixed cardinality dimension for the vector and a fixed similarity function.
+ * The default similarity is EUCLIDEAN_HNSW (L2).
+ * See subclasses for details.
+ *
+ * <br>
+ * Only {@code Indexed} and {@code Stored} attributes are supported.
+ */
+public class DenseVectorField extends FieldType {
+
+    static final String KNN_VECTOR_DIMENSION = "vectorDimension";
+    static final String KNN_SIMILARITY_FUNCTION = "similarityFunction";
+    
+    int dimension;
+    VectorSimilarityFunction similarityFunction;
+    VectorSimilarityFunction DEFAULT_SIMILARITY = VectorSimilarityFunction.EUCLIDEAN;
+
+    @Override
+    public void init(IndexSchema schema, Map<String, String> args){
+        this.dimension = ofNullable(args.get(KNN_VECTOR_DIMENSION))
+                .map(value -> parseDimensionParameter(value))
+                .orElseThrow(() -> new SolrException(SolrException.ErrorCode.SERVER_ERROR, "the vector dimension is a mandatory parameter"));
+        args.remove(KNN_VECTOR_DIMENSION);
+
+        this.similarityFunction = ofNullable(args.get(KNN_SIMILARITY_FUNCTION))
+                .map(value -> VectorSimilarityFunction.valueOf(value.toUpperCase(Locale.ROOT)))
+                .orElse(DEFAULT_SIMILARITY);
+        args.remove(KNN_SIMILARITY_FUNCTION);
+
+        this.properties &= ~MULTIVALUED;
+        this.properties &= ~UNINVERTIBLE;
+        
+        super.init(schema, args);
+    }
+
+    private int parseDimensionParameter(String value) {
+        try {
+            return Integer.parseInt(value);
+        } catch (NumberFormatException e) {
+            throw new SolrException(SolrException.ErrorCode.SERVER_ERROR, "the vector dimension must be an integer");
+        }
+    }
+
+    @Override
+    public void checkSchemaField(final SchemaField field) throws SolrException {
+        super.checkSchemaField(field);
+        if (field.multiValued()) {
+            throw new SolrException(SolrException.ErrorCode.SERVER_ERROR,
+                    getClass().getSimpleName() + " fields can not be multiValued: " + field.getName());
+        }
+    }
+    
+    public List<IndexableField> createFields(SchemaField field, Object value) {
+        List<IndexableField> fields = new ArrayList<>();
+        if (field.indexed()){
+            fields.add(createField(field, value));
+        }
+        if (field.stored()){
+            fields.add(createStoredField(field, value));
+        }
+        return fields;
+    }
+
+    private IndexableField createStoredField(SchemaField field, Object value) {
+        return new StoredField(field.getName(), value.toString());
+    }
+
+    @Override
+    public UninvertingReader.Type getUninversionType(SchemaField sf) {
+        return null;
+    }
+
+    @Override
+    public ValueSource getValueSource(SchemaField field, QParser parser) {
+        throw new SolrException(SolrException.ErrorCode.BAD_REQUEST,
+                "Function queries are not supported for Dense Vector fields.");
+    }
+
+    @Override
+    public void write(TextResponseWriter writer, String name, IndexableField f) throws IOException {
+        writer.writeVal(name, f.stringValue());

Review comment:
       Not sure what stringValue will return here - will it be the `Arrays.toString()` of the vector? Something else?

##########
File path: solr/core/src/java/org/apache/solr/schema/DenseVectorField.java
##########
@@ -0,0 +1,200 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.solr.schema;
+
+import org.apache.lucene.document.KnnVectorField;
+import org.apache.lucene.document.StoredField;
+import org.apache.lucene.index.IndexableField;
+import org.apache.lucene.index.VectorSimilarityFunction;
+import org.apache.lucene.queries.function.ValueSource;
+import org.apache.lucene.search.KnnVectorQuery;
+import org.apache.lucene.search.Query;
+import org.apache.lucene.search.SortField;
+import org.apache.solr.common.SolrException;
+import org.apache.solr.response.TextResponseWriter;
+import org.apache.solr.search.QParser;
+import org.apache.solr.uninverting.UninvertingReader;
+
+import java.io.IOException;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
+
+import static java.util.Optional.ofNullable;
+
+/**
+ * Provides a field type to support Lucene's {@link
+ * org.apache.lucene.document.KnnVectorField}.
+ * See {@link org.apache.lucene.search.KnnVectorQuery} for more details.
+ * It supports a fixed cardinality dimension for the vector and a fixed similarity function.
+ * The default similarity is EUCLIDEAN_HNSW (L2).
+ * See subclasses for details.
+ *
+ * <br>
+ * Only {@code Indexed} and {@code Stored} attributes are supported.
+ */
+public class DenseVectorField extends FieldType {
+
+    static final String KNN_VECTOR_DIMENSION = "vectorDimension";
+    static final String KNN_SIMILARITY_FUNCTION = "similarityFunction";
+    
+    int dimension;
+    VectorSimilarityFunction similarityFunction;
+    VectorSimilarityFunction DEFAULT_SIMILARITY = VectorSimilarityFunction.EUCLIDEAN;
+
+    @Override
+    public void init(IndexSchema schema, Map<String, String> args){
+        this.dimension = ofNullable(args.get(KNN_VECTOR_DIMENSION))
+                .map(value -> parseDimensionParameter(value))
+                .orElseThrow(() -> new SolrException(SolrException.ErrorCode.SERVER_ERROR, "the vector dimension is a mandatory parameter"));
+        args.remove(KNN_VECTOR_DIMENSION);
+
+        this.similarityFunction = ofNullable(args.get(KNN_SIMILARITY_FUNCTION))
+                .map(value -> VectorSimilarityFunction.valueOf(value.toUpperCase(Locale.ROOT)))
+                .orElse(DEFAULT_SIMILARITY);
+        args.remove(KNN_SIMILARITY_FUNCTION);
+
+        this.properties &= ~MULTIVALUED;
+        this.properties &= ~UNINVERTIBLE;
+        
+        super.init(schema, args);
+    }
+
+    private int parseDimensionParameter(String value) {
+        try {
+            return Integer.parseInt(value);
+        } catch (NumberFormatException e) {
+            throw new SolrException(SolrException.ErrorCode.SERVER_ERROR, "the vector dimension must be an integer");
+        }
+    }
+
+    @Override
+    public void checkSchemaField(final SchemaField field) throws SolrException {
+        super.checkSchemaField(field);
+        if (field.multiValued()) {
+            throw new SolrException(SolrException.ErrorCode.SERVER_ERROR,
+                    getClass().getSimpleName() + " fields can not be multiValued: " + field.getName());
+        }
+    }
+    
+    public List<IndexableField> createFields(SchemaField field, Object value) {
+        List<IndexableField> fields = new ArrayList<>();
+        if (field.indexed()){
+            fields.add(createField(field, value));
+        }
+        if (field.stored()){
+            fields.add(createStoredField(field, value));
+        }
+        return fields;
+    }
+
+    private IndexableField createStoredField(SchemaField field, Object value) {
+        return new StoredField(field.getName(), value.toString());
+    }
+
+    @Override
+    public UninvertingReader.Type getUninversionType(SchemaField sf) {
+        return null;
+    }
+
+    @Override
+    public ValueSource getValueSource(SchemaField field, QParser parser) {
+        throw new SolrException(SolrException.ErrorCode.BAD_REQUEST,
+                "Function queries are not supported for Dense Vector fields.");
+    }
+
+    @Override
+    public void write(TextResponseWriter writer, String name, IndexableField f) throws IOException {
+        writer.writeVal(name, f.stringValue());
+    }
+
+    @Override
+    public IndexableField createField(SchemaField field, Object value) {
+        float[] parsedVector;
+        try {
+            parsedVector = parseVector(value.toString());
+        } catch (RuntimeException e) {
+            throw new SolrException(SolrException.ErrorCode.SERVER_ERROR, "Error while creating field '" + field + "' from value '" + value + "', expected format:'[f1, f2, f3...fn]' e.g. [1.0, 3.4, 5.6]", e);
+        }
+        if (parsedVector == null) return null;
+
+        return new KnnVectorField(field.getName(), parsedVector, similarityFunction);
+    }
+
+    /**
+     * Parses a String vector.
+     *
+     * @param value with format: [f1, f2, f3, f4...fn]

Review comment:
       Have you considered an alternate more compressed string format? Maybe b64-encode the bytes of the float array?




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on pull request #476: SOLR-15880

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on pull request #476:
URL: https://github.com/apache/solr/pull/476#issuecomment-1002617717


   @msokolov thanks for the very good insights.
   I proceeded with an extensive work of analysis for the serialization/deserialization, especially investigating the available loaders in Solr (XML, JSON, Javabin and CSV).
   I am finalizing quite an extensive change (including testing).
   Moving away from "stringification" and leveraging arrays of numerics.
   I'll update the Pull Request once polished in the next few days!


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880: K Nearest Neighbors Search

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r787664495



##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not be solved simply by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+
+=== DenseVectorField
+The Dense Vector field gives the possibility of indexing and searching dense vectors of float elements.
+
+e.g.
+
+`[1.0, 2.5, 3.7, 4.1]` (array of float elements)
+
+Here's how `DenseVectorField` should be configured in the schema:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`vectorDimension`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The dimension of the dense vector to pass in.
++
+Accepted values:
+Integer < = 1024.
+
+`similarityFunction`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `euclidean`
+|===
++
+Vector similarity function; used in search to return top K most similar vectors to a target vector.
++
+Accepted values: `euclidean`, `dot_product`  or `cosine`.
+
+* `euclidean`: https://en.wikipedia.org/wiki/Euclidean_distance[Euclidean distance]
+* `dot_product`: https://en.wikipedia.org/wiki/Dot_product[Dot product]. *NOTE*: this similarity is intended as an optimized way to perform cosine similarity. In order to use it, all vectors must be of unit length, including both document and query vectors. Using dot product with vectors that are not unit length can result in errors or poor search results..
+* `cosine`: https://en.wikipedia.org/wiki/Cosine_similarity[Cosine similarity]. *NOTE*: the preferred way to perform cosine similarity is to normalize all vectors to unit length, and instead use DOT_PRODUCT. You should only use this function if you need to preserve the original vectors and cannot normalize them in advance.
+
+*N.B.* To use the following advanced parameters that customise the codec format
+and the hyper-parameter of the HNSW algorithm make sure you set this configuration in the solrconfig.xml:
+[source,xml]
+<config>
+<codecFactory class="solr.SchemaCodecFactory"/>
+...
+
+Here's how `DenseVectorField` can be configured with the advanced codec hyper-parameters:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine" codecFormat="Lucene90HnswVectorsFormat" hnswMaxConnections="10" hnswBeamWidth="40"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`codecFormat`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `Lucene90HnswVectorsFormat`
+|===
++
+(advanced) Specifies the knn codec implementation to use
++
+
+Accepted values: `Lucene90HnswVectorsFormat`.
+
+Please note that the `codecFormat` accepted values may change in future releases.
+
+
+
+[NOTE]
+Lucene index back-compatibility is only supported for the default codec.
+If you choose to customize the `codecFormat` in your schema, upgrading to a future version of Solr may require you to either switch back to the default codec and optimize your index to rewrite it into the default codec before upgrading, or re-build your entire index from scratch after upgrading.
+
+`hnswMaxConnections`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 16
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+Controls how many of the nearest neighbor candidates are connected to the new node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `M` from the later paper.
++
+Accepted values:
+Integer.
+
+`hnswBeamWidth`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 100
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+It is the number of nearest neighbor candidates to track while searching the graph for each newly inserted node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `efConstruction` from the later paper.
++
+Accepted values:
+Integer.
+
+DenseVectorField supports the attributes: `indexed`, `stored`.
+
+*N.B.* currently multivalue is not supported
+
+Here's how a `DenseVectorField` should be indexed:
+
+[.dynamic-tabs]
+--
+[example.tab-pane#json]
+====
+[.tab-label]*JSON*
+[source,json]
+----
+[{ "id": "1",
+"vector": [1.0, 2.5, 3.7, 4.1]
+},
+{ "id": "2",
+"vector": [1.5, 5.5, 6.7, 65.1]
+}
+]
+----
+====
+
+[example.tab-pane#xml]
+====
+[.tab-label]*XML*
+[source,xml]
+----
+<add>
+<doc>
+<field name="id">1</field>
+<field name="vector">1.0</field>
+<field name="vector">2.5</field>
+<field name="vector">3.7</field>
+<field name="vector">4.1</field>
+</doc>
+<doc>
+<field name="id">2</field>
+<field name="vector">1.5</field>
+<field name="vector">5.5</field>
+<field name="vector">6.7</field>
+<field name="vector">65.1</field>
+</doc>
+</add>
+----
+====
+
+[example.tab-pane#solrj]
+====
+[.tab-label]*SolrJ*
+[source,java,indent=0]
+----
+final SolrClient client = getSolrClient();
+
+final SolrInputDocument d1 = new SolrInputDocument();
+d1.setField("id", "1");
+d1.setField("vector", Arrays.asList(1.0f, 2.5f, 3.7f, 4.1f));
+
+
+final SolrInputDocument d2 = new SolrInputDocument();
+d2.setField("id", "2");
+d2.setField("vector", Arrays.asList(1.5f, 5.5f, 6.7f, 65.1f));
+
+client.add(Arrays.asList(d1, d2));
+----
+====
+--
+
+== Query Time
+This is the list of Apache Solr query approaches designed to support Neural Search:
+
+=== knn Query Parser
+The `knn` K-Nearest Neighbors query parser allows to find the k-nearest documents to the target vector according to indexed dense vectors in the given field.
+
+The score for a retrieved document is the approximate distance to the target vector(defined by the similarityFunction configured at indexing time).
+
+It takes the following parameters:
+
+`f`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The DenseVectorField to search in.

Review comment:
       Done!




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880: K Nearest Neighbors Search

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r787961228



##########
File path: solr/solr-ref-guide/src/dense-vector-search.adoc
##########
@@ -0,0 +1,308 @@
+= Dense Vector Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+The Apache Solr *Dense Vector Search* module adds support for indexing and searching dense numerical vectors.
+
+https://en.wikipedia.org/wiki/Deep_learning[Deep learning] can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+These neural network-based techniques are usually referred as neural search, an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].

Review comment:
       Thanks, Michael! Done!




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880: K Nearest Neighbors Search

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r787613104



##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,733 @@
+= Neural Search

Review comment:
       As the author of the documentation obviously I think "Neural Search" as a headline is all right.
   I think it's becoming accepted generally by the Information Retrieval community and it's easily recognizable.
   I don't have a strong opinion though and I am happy to revise the title if the community prefers.
   Let me explain some of my motivations:
   1) it's becoming more and more adopted in the industry and in the academy to label search aspects that use directly or byproducts of neural networks(vector embeddings)
   2) Dense Vector Search is not wrong per se, but my idea is to extend the documentation in the future with additional neural-based techniques and components, and I see them better documented and reachable if under the same section.
   Whenever the section becomes too big (hopefully) we can then split it across many different pages?
   3) I don't think the section must be fully comprehensive from the beginning, I think it's all right there are aspects of Neural Search that are not addressed right now. It's actually a good incentive for the community to contribute, improve and extend the support in the future.
   4) I agree with this headline we'll get some attention, but I see this is a benefit, a lot of fresh attention to the Apache Solr project can bring more curiosity in and more contributions. I don't think there's anywhere in the documentation that hint at "false advertisement" and that can cause the feeling of under-delivering a larger promise?
   




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] magibney commented on a change in pull request #476: SOLR-15880: K Nearest Neighbors Search

Posted by GitBox <gi...@apache.org>.
magibney commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r789890276



##########
File path: solr/solr-ref-guide/src/dense-vector-search.adoc
##########
@@ -0,0 +1,308 @@
+= Dense Vector Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+The Apache Solr *Dense Vector Search* module adds support for indexing and searching dense numerical vectors.
+
+https://en.wikipedia.org/wiki/Deep_learning[Deep learning] can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+These neural network-based techniques are usually referred to as neural search, an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Important Concepts
+
+=== Dense Vector Representation 
+A dense vector describes information as an array of elements, each of them explicitly defined.

Review comment:
       Thanks! I took another pass at this below.
   
   Starting from your latest revision, I partially reverted a few things to the original version I drafted (mostly just the beginning of the first paragraph). I stuck with your reformatting into more separate paragraphs, and I appreciated your reduction of my "overuse" of "quotes" :-) -- so left that as you had it.
   
   I also left the two places where you replaced "Solr" with "Apache Solr", though personally I'd be inclined to go with the more succinct "Solr"? I linked to the wikipedia page for "inverted index", analogous to what you had done for "Bag of words" -- though I'm not sure the external link is necessary.
   
   The only other change I introduced was "distills semantic meaning" => "distills _approximate_ semantic meaning". I don't feel too strongly about that, but I do think it's more accurate, and lets us humans continue to feel special :-)
    
   >=== Dense Vector Representation 
   >A traditional tokenized https://en.wikipedia.org/wiki/Inverted_index[inverted index] can be considered to model text as a "sparse" vector, in which each term in the corpus corresponds to one vector dimension. In such a model, the number of dimensions is generally quite high (corresponding to the term dictionary cardinality), and the vector for any given document contains mostly zeros (hence it is sparse, as only a handful of terms that exist in the overall index will be present in any given document).
   >
   >Dense vector representation contrasts with term-based sparse vector representation in that it distills approximate semantic meaning into a fixed (and limited) number of dimensions.
   >
   >The number of dimensions in this approach is generally much lower than the sparse case, and the vector for any given document is dense, as most of its dimensions are populated by non-zero values.
   >
   >In contrast to the sparse approach (for which tokenizers are used to generate sparse vectors directly from text input) the task of generating vectors must be handled in application logic external to Apache Solr.
   >
   >There may be cases where it makes sense to directly search data that natively exists as a vector (e.g., scientific data); but in a text search context, it is likely that users will leverage deep learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] to encode textual information as dense vectors, supplying the resulting vectors to Apache Solr explicitly at index and query time.
   >
   >For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] magibney commented on a change in pull request #476: SOLR-15880: K Nearest Neighbors Search

Posted by GitBox <gi...@apache.org>.
magibney commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r788954745



##########
File path: solr/solr-ref-guide/src/dense-vector-search.adoc
##########
@@ -0,0 +1,308 @@
+= Dense Vector Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+The Apache Solr *Dense Vector Search* module adds support for indexing and searching dense numerical vectors.
+
+https://en.wikipedia.org/wiki/Deep_learning[Deep learning] can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+These neural network-based techniques are usually referred to as neural search, an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Important Concepts
+
+=== Dense Vector Representation 
+A dense vector describes information as an array of elements, each of them explicitly defined.

Review comment:
       Ahh I see! Sorry for the delayed response. I'll take a crack at this, feel free to take or leave this suggestion:
   
   >=== Dense Vector Representation 
   >A traditional "tokenized inverted index" can be considered to model text as a "sparse" vector, in which each term in the index corresponds to one vector dimension. In such a model, the number of dimensions is generally quite high (corresponding to term cardinality), and the vector for any given document contains mostly "zeros" (hence it is "sparse", as only a handful of terms that exist in the overall index will be present in any given document).
   >
   >"Dense vector" representation contrasts with term-based "sparse vector" representation in that it distills semantic meaning into a fixed (and limited) number of dimensions. The number of dimensions in this approach is generally much lower than the "sparse" case, and the vector for any given document is "dense", as most of its dimensions are populated by non-zero values.
   >
   >Solr exposes the capability to index and search dense vectors; but in contrast to the "sparse" approach (for which Solr provides tokenizers to "generate sparse vectors" directly from text input) the task of _generating_ vectors must be handled in application logic external to Solr. There may be cases where it makes sense to directly search data that natively exists as a vector (e.g., scientific data); but in a "text search" context, it is likely that users will leverage deep learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] to encode textual information as dense vectors, supplying the resulting vectors to Solr explicitly at index and query time.




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880: K Nearest Neighbors Search

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r788030566



##########
File path: solr/solr-ref-guide/src/dense-vector-search.adoc
##########
@@ -0,0 +1,308 @@
+= Dense Vector Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+The Apache Solr *Dense Vector Search* module adds support for indexing and searching dense numerical vectors.
+
+https://en.wikipedia.org/wiki/Deep_learning[Deep learning] can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+These neural network-based techniques are usually referred to as neural search, an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Important Concepts
+
+=== Dense Vector Representation 
+A dense vector describes information as an array of elements, each of them explicitly defined.

Review comment:
       my intention was to clarify the distinction between dense and sparse vectors, I have just refined the doc, let me know if it's any better.
   Feel free to recommend any addition and I'll add it!
   As a non-native speaker/writer, I am finding this feedback on the documentation extremely valuable, I am really grateful!




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on pull request #476: SOLR-15880

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on pull request #476:
URL: https://github.com/apache/solr/pull/476#issuecomment-1015427794


   Thanks, @cpoerschke for the thoughtful review, I committed all your suggestions!


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] magibney commented on a change in pull request #476: SOLR-15880: K Nearest Neighbors Search

Posted by GitBox <gi...@apache.org>.
magibney commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r789773406



##########
File path: solr/solr-ref-guide/src/dense-vector-search.adoc
##########
@@ -0,0 +1,308 @@
+= Dense Vector Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+The Apache Solr *Dense Vector Search* module adds support for indexing and searching dense numerical vectors.
+
+https://en.wikipedia.org/wiki/Deep_learning[Deep learning] can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+These neural network-based techniques are usually referred to as neural search, an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Important Concepts
+
+=== Dense Vector Representation 
+A dense vector describes information as an array of elements, each of them explicitly defined.

Review comment:
       Thanks, Alessandro!
   
   I think maybe we should go either/or with reference to "Bag of words" vs. "Inverted index". In the text I drafted I referred to an "inverted index" as an example of sparse vector representation because I figured it would likely be the most familiar reference point for the "Solr refguide" audience.
   
   I note that Wikipedia has two separate entries: [Bag-of-words model](https://en.wikipedia.org/wiki/Bag-of-words_model) and [Inverted index](https://en.wikipedia.org/wiki/Inverted_index), neither of which refers directly to the other, but both of which include a "See also" reference to the page for [Vector space model](https://en.wikipedia.org/wiki/Vector_space_model). The wikipedia pages are explicit about one difference, with the second clearly describing how most people use Solr:
   1. "The Bag-of-words model is an orderless document representation — only the counts of words matter."
   2. "A word-level inverted index (or full inverted index or inverted list) additionally contains the positions of each word within a document.[2] The latter form offers more functionality (like phrase searches)"
   
   Either model is arguably a valid example of a "sparse vector" representation. My practical concern is that in this context, it would be easy to misinterpret the reference to "Bag of words" as an implicit reference to "_non-vector_ search in Solr", whatever the intention of using "Bag-of-words" as a point of reference. I think that interpretation would be misleading, and could obscure the true distinction between "dense vector search" and classic TF-IDF/BM25/phrase-boosted/etc. search in Solr, and the appropriate use cases for each approach.
   
   (minor point: I'd also be inclined to drop the separate heading for "Sparse Vector Representation" -- I was purposefully vague in saying `can be considered to model text as a "sparse" vector`; perhaps I'm mistaken, but my impression is that "sparse" retrieval models (as _accurate_ as that characterization may be), are most often characterized as "sparse" as a foil to explain why "dense retrieval" is characterized as "dense". Indeed, that's what we're doing here!)




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r786779115



##########
File path: solr/core/src/java/org/apache/solr/search/neural/KnnQParser.java
##########
@@ -0,0 +1,101 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.solr.search.neural;
+
+import org.apache.commons.lang3.StringUtils;
+import org.apache.lucene.search.Query;
+import org.apache.solr.common.SolrException;
+import org.apache.solr.common.params.SolrParams;
+import org.apache.solr.request.SolrQueryRequest;
+import org.apache.solr.schema.DenseVectorField;
+import org.apache.solr.schema.FieldType;
+import org.apache.solr.schema.SchemaField;
+import org.apache.solr.search.QParser;
+import org.apache.solr.search.QueryParsing;
+
+public class KnnQParser extends QParser {
+
+    static final String TOP_K = "topK";// retrieve the top K results based on the distance similarity function 
+    static final int DEFAULT_TOP_K = 10;
+
+    /**
+     * Constructor for the QParser
+     *
+     * @param qstr        The part of the query string specific to this parser
+     * @param localParams The set of parameters that are specific to this QParser.  See https://solr.apache.org/guide/local-parameters-in-queries.html
+     * @param params      The rest of the {@link SolrParams}
+     * @param req         The original {@link SolrQueryRequest}.
+     */
+    public KnnQParser(String qstr, SolrParams localParams, SolrParams params, SolrQueryRequest req) {
+        super(qstr, localParams, params, req);
+    }
+
+    @Override
+    public Query parse() {
+        String denseVectorField = localParams.get(QueryParsing.F);
+        String vectorToSearch = localParams.get(QueryParsing.V);
+        int topK = localParams.getInt(TOP_K, DEFAULT_TOP_K);
+
+        if (denseVectorField == null || denseVectorField.isEmpty()) {
+            throw new SolrException(SolrException.ErrorCode.BAD_REQUEST, "the Dense Vector field 'f' is missing");
+        }
+
+        if (vectorToSearch == null || vectorToSearch.isEmpty()) {
+            throw new SolrException(SolrException.ErrorCode.BAD_REQUEST, "the Dense Vector to search is missing");
+        }
+
+        SchemaField schemaField = req.getCore().getLatestSchema().getField(denseVectorField);
+        FieldType fieldType = schemaField.getType();
+        if (!(fieldType instanceof DenseVectorField)) {
+            throw new SolrException(SolrException.ErrorCode.BAD_REQUEST, "only DenseVectorField is compatible with Knn Query Parser");
+        }
+
+        DenseVectorField denseVectorType = (DenseVectorField) fieldType;
+        float[] parsedVectorToSearch = parseVector(vectorToSearch, denseVectorType.getDimension());
+        return denseVectorType.getKnnVectorQuery(schemaField, parsedVectorToSearch, topK);

Review comment:
       Done!




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] magibney commented on a change in pull request #476: SOLR-15880: K Nearest Neighbors Search

Posted by GitBox <gi...@apache.org>.
magibney commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r787959876



##########
File path: solr/solr-ref-guide/src/dense-vector-search.adoc
##########
@@ -0,0 +1,308 @@
+= Dense Vector Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+The Apache Solr *Dense Vector Search* module adds support for indexing and searching dense numerical vectors.
+
+https://en.wikipedia.org/wiki/Deep_learning[Deep learning] can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+These neural network-based techniques are usually referred as neural search, an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].

Review comment:
       minor typo: "usually referred _to_ as neural search"




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r786713512



##########
File path: solr/core/src/java/org/apache/solr/schema/DenseVectorField.java
##########
@@ -0,0 +1,256 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.solr.schema;
+
+import org.apache.lucene.codecs.lucene90.Lucene90HnswVectorsFormat;
+import org.apache.lucene.document.KnnVectorField;
+import org.apache.lucene.index.IndexableField;
+import org.apache.lucene.index.VectorSimilarityFunction;
+import org.apache.lucene.queries.function.ValueSource;
+import org.apache.lucene.search.KnnVectorQuery;
+import org.apache.lucene.search.Query;
+import org.apache.lucene.search.SortField;
+import org.apache.lucene.util.hnsw.HnswGraph;
+import org.apache.solr.common.SolrException;
+import org.apache.solr.search.QParser;
+import org.apache.solr.uninverting.UninvertingReader;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
+
+import static java.util.Optional.ofNullable;
+import static org.apache.lucene.codecs.lucene90.Lucene90HnswVectorsFormat.DEFAULT_BEAM_WIDTH;
+import static org.apache.lucene.codecs.lucene90.Lucene90HnswVectorsFormat.DEFAULT_MAX_CONN;
+
+/**
+ * Provides a field type to support Lucene's {@link
+ * org.apache.lucene.document.KnnVectorField}.
+ * See {@link org.apache.lucene.search.KnnVectorQuery} for more details.
+ * It supports a fixed cardinality dimension for the vector and a fixed similarity function.
+ * The default similarity is EUCLIDEAN_HNSW (L2).
+ * The default index codec format is specified in the Lucene Codec constructor.
+ * For Lucene 9.0 e.g.
+ * See {@link org.apache.lucene.codecs.lucene90.Lucene90Codec}
+ * Currently only {@link org.apache.lucene.codecs.lucene90.Lucene90HnswVectorsFormat} is supported for
+ * advanced hyper-parameter customisation.
+ * See {@link org.apache.lucene.util.hnsw.HnswGraph} for more details about the implementation. 
+ *
+ * <br>
+ * Only {@code Indexed} and {@code Stored} attributes are supported.
+ */
+public class DenseVectorField extends FloatPointField {
+
+    static final String KNN_VECTOR_DIMENSION = "vectorDimension";
+    static final String KNN_SIMILARITY_FUNCTION = "similarityFunction";
+    
+    static final String CODEC_FORMAT = "codecFormat";
+    static final String HNSW_MAX_CONNECTIONS = "hnswMaxConnections";
+    static final String HNSW_BEAM_WIDTH = "hnswBeamWidth";
+
+    int dimension;
+    VectorSimilarityFunction similarityFunction;
+    VectorSimilarityFunction DEFAULT_SIMILARITY = VectorSimilarityFunction.EUCLIDEAN;
+
+    String codecFormat;
+    /**
+     * This parameter is coupled with the {@link Lucene90HnswVectorsFormat} format implementation.
+     * Controls how many of the nearest neighbor candidates are connected to the new node. Defaults to
+     * {@link Lucene90HnswVectorsFormat#DEFAULT_MAX_CONN}. See {@link HnswGraph} for more details.
+     */
+    int hnswMaxConn;
+    /**
+     * This parameter is coupled with the {@link Lucene90HnswVectorsFormat} format implementation.
+     * The number of candidate neighbors to track while searching the graph for each newly inserted
+     * node. Defaults to to {@link Lucene90HnswVectorsFormat#DEFAULT_BEAM_WIDTH}. See {@link
+     * HnswGraph} for details.
+     */
+    int hnswBeamWidth;

Review comment:
       Done! and tests adapted




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880: K Nearest Neighbors Search

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r787639181



##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not be solved simply by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+

Review comment:
       I wanted to make a clear distinction between the "Index time" components and Query Time components.
   Yes I agree at the moment we have just one of each, but I still think it's more readable to clearly put them under their appropriate section(Index/Query).
   
   I removed "list", I agree we can add it when they become more than one.
   But I would prefer to keep the Index time/ query time paragraph.
   let me know what do you think!




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880: K Nearest Neighbors Search

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r787822360



##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,733 @@
+= Neural Search

Review comment:
       From Slack:
   "t makes sense and I you convinced me!
   You are the Apache Solr Ref leader for a reason :slightly_smiling_face:
   I'll change the documentation page, but I'll keep referring to this (and future) contributions as neural features (for sure it can be considered a "marketing" friendly name, but my genuinely attempt is to use the best reference for this upcoming features, as used around).
   I have one final question in relation to a possible next feature(s) arriving.
   For example we are planning to contribute an automatic synonyms generation endpoint that leverages neural networks.
   At that point in your opinion would be fine to restructure the documentation creating a parent page:
   Neural Search with two children?
   Dense Vector Retrieval
   Neural Network Synonym Generation
   ect ect ?
   thanks again for the very useful review @Cassandra, much appreciated"




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] msokolov commented on pull request #476: SOLR-15880: K Nearest Neighbors Search

Posted by GitBox <gi...@apache.org>.
msokolov commented on pull request #476:
URL: https://github.com/apache/solr/pull/476#issuecomment-1028997829


   We put in a limit of 1024 since we need *some* limit in order to help people not to shoot themselves in the foot and then blame the software... What dimension in fact are your vectors? Maybe consider adding some dimensionality reduction step? Sorry I don't know what a ResNet is :) 


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti merged pull request #476: SOLR-15880: K Nearest Neighbors Search

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti merged pull request #476:
URL: https://github.com/apache/solr/pull/476


   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] epugh commented on a change in pull request #476: SOLR-14397

Posted by GitBox <gi...@apache.org>.
epugh commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r774822329



##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,733 @@
+= Neural Search

Review comment:
       SUper excited to see this page written ;-)   Neural Search is the future.




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on pull request #476: SOLR-15880

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on pull request #476:
URL: https://github.com/apache/solr/pull/476#issuecomment-1001609366


   thanks @msokolov for your initial feedback!
   me and @eliaporciani will think about it and design some changes in the next few days!


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] risdenk commented on a change in pull request #476: SOLR-15880

Posted by GitBox <gi...@apache.org>.
risdenk commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r783202537



##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,320 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+With the *Neural Search* module Apache Solr is introducing support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not simply be solved by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+
+=== DenseVectorField
+The Dense Vector field gives the possibility of indexing and searching dense vectors of float elements.
+
+e.g.
+
+`[1.0, 2.5, 3.7, 4.1]` (array of float elements)
+
+Here's how `DenseVectorField` should be configured in the schema:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`vectorDimension`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The dimension of the dense vector to pass in.
++
+Accepted values:
+Integer < = 1024.
+
+`similarityFunction`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `euclidean`
+|===
++
+Vector similarity function; used in search to return top K most similar vectors to a target vector.
++
+Accepted values: `euclidean`, `dot_product`  or `cosine`.
+
+* `euclidean`: https://en.wikipedia.org/wiki/Euclidean_distance[Euclidean distance]
+* `dot_product`: https://en.wikipedia.org/wiki/Dot_product[Dot product]. *NOTE*: this similarity is intended as an optimized way to perform cosine similarity. In order to use it, all vectors must be of unit length, including both document and query vectors. Using dot product with vectors that are not unit length can result in errors or poor search results..
+* `cosine`: https://en.wikipedia.org/wiki/Cosine_similarity[Cosine similarity]. *NOTE*: the preferred way to perform cosine similarity is to normalize all vectors to unit length, and instead use DOT_PRODUCT. You should only use this function if you need to preserve the original vectors and cannot normalize them in advance.
+
+*N.B.* To use the following advanced parameters that customise the codec format
+and the hyper-parameter of the HNSW algorithm make sure you set this configuration in the solrconfig.xml:
+[source,xml]
+<config>
+<codecFactory class="solr.SchemaCodecFactory"/>
+...
+
+Here's how `DenseVectorField` can be configured with the advanced codec hyper-parameters:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine" codecFormat="Lucene90HnswVectorsFormat" hnswMaxConnections="10" hnswBeamWidth="40"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`codecFormat`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `Lucene90HnswVectorsFormat`
+|===
++
+(advanced) Specifies the knn codec implementation to use
++
+
+Accepted values: `Lucene90HnswVectorsFormat`.
+
+Please note that the `codecFormat` accepted values may change in future releases.
+
+
+
+[NOTE]
+Lucene index back-compatibility is only supported for the default codec.
+If you choose to customize the `codecFormat` in your schema, upgrading to a future version of Solr may require you to either switch back to the default codec and optimize your index to rewrite it into the default codec before upgrading, or re-build your entire index from scratch after upgrading.
+
+`hnswMaxConnections`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 16
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+Controls how many of the nearest neighbor candidates are connected to the new node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `M` from the later paper.
++
+Accepted values:
+Integer.
+
+`hnswBeamWidth`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 100
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+It is the number of nearest neighbor candidates to track while searching the graph for each newly inserted node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `efConstruction` from the later paper.
++
+Accepted values:
+Integer.
+
+DenseVectorField supports the attributes: `indexed`, `stored`.
+
+*N.B.* currently multivalue is not supported
+
+Here's how a `DenseVectorField` should be indexed:
+
+[.dynamic-tabs]
+--
+[example.tab-pane#json]
+====
+[.tab-label]*JSON*
+[source,json]
+----
+[{ "id": "1",
+"vector": [1.0, 2.5, 3.7, 4.1]
+},
+{ "id": "2",
+"vector": [1.5, 5.5, 6.7, 65.1]
+}
+]
+----
+====
+
+[example.tab-pane#xml]
+====
+[.tab-label]*XML*
+[source,xml]
+----
+<add>
+<doc>
+<field name="id">1</field>
+<field name="vector">1.0</field>
+<field name="vector">2.5</field>
+<field name="vector">3.7</field>
+<field name="vector">4.1</field>
+</doc>
+<doc>
+<field name="id">2</field>
+<field name="vector">1.5</field>
+<field name="vector">5.5</field>
+<field name="vector">6.7</field>
+<field name="vector">65.1</field>
+</doc>
+</add>
+----
+====
+
+[example.tab-pane#solrj]
+====
+[.tab-label]*SolrJ*
+[source,java,indent=0]
+----
+final SolrClient client = getSolrClient();
+
+final SolrInputDocument d1 = new SolrInputDocument();
+d1.setField("id", "1");
+d1.setField("vector", Arrays.asList(1.0f, 2.5f, 3.7f, 4.1f));
+
+
+final SolrInputDocument d2 = new SolrInputDocument();
+d2.setField("id", "2");
+d2.setField("vector", Arrays.asList(1.5f, 5.5f, 6.7f, 65.1f));
+
+client.add(Arrays.asList(d1, d2));
+----
+====
+--
+
+== Query Time
+This is the list of Apache Solr query approaches designed to support Neural Search:
+
+=== knn Query Parser
+The `knn` K-Nearest Neighbors query parser allows to find the k-nearest documents to the target vector according to indexed dense vectors in the given field.
+
+It takes the following parameters:
+
+`f`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The DenseVectorField to search in.
+
+`topK`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 10
+|===
++
+How many k-nearest results to return.
+
+Here's how to run a KNN search:
+
+[source,text]
+&q={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]
+
+The search results retrieved are the K-nearest to the vector in input `[1.0, 2.0, 3.0, 4.0]`, ranked by the similarityFunction configured at indexing time.

Review comment:
       Thanks makes a ton of sense.




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] risdenk commented on a change in pull request #476: SOLR-15880

Posted by GitBox <gi...@apache.org>.
risdenk commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r783204525



##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,320 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+With the *Neural Search* module Apache Solr is introducing support for neural networks based techniques that can improve various aspects of search.

Review comment:
       ```suggestion
   The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
   ```
   
   Reworded again to maybe be a bit more clear and direct. 




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r783023194



##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,320 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+With the *Neural Search* module Apache Solr is introducing support for neural networks based techniques that can improve various aspects of search.

Review comment:
       I am not a native speaker, but is "With the *Neural Search* module Apache Solr is support for neural networks based techniques" correct? I didn't know of the construct:
   "with <something> Apache Solr is support for <something>
   




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] fmmoret commented on a change in pull request #476: SOLR-15880

Posted by GitBox <gi...@apache.org>.
fmmoret commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r777270725



##########
File path: solr/core/src/java/org/apache/solr/schema/DenseVectorField.java
##########
@@ -0,0 +1,211 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.solr.schema;
+
+import org.apache.lucene.document.KnnVectorField;
+import org.apache.lucene.index.IndexableField;
+import org.apache.lucene.index.VectorSimilarityFunction;
+import org.apache.lucene.queries.function.ValueSource;
+import org.apache.lucene.search.KnnVectorQuery;
+import org.apache.lucene.search.Query;
+import org.apache.lucene.search.SortField;
+import org.apache.solr.common.SolrException;
+import org.apache.solr.search.QParser;
+import org.apache.solr.uninverting.UninvertingReader;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
+
+import static java.util.Optional.ofNullable;
+
+/**
+ * Provides a field type to support Lucene's {@link
+ * org.apache.lucene.document.KnnVectorField}.
+ * See {@link org.apache.lucene.search.KnnVectorQuery} for more details.
+ * It supports a fixed cardinality dimension for the vector and a fixed similarity function.
+ * The default similarity is EUCLIDEAN_HNSW (L2).
+ * See subclasses for details.
+ *
+ * <br>
+ * Only {@code Indexed} and {@code Stored} attributes are supported.
+ */
+public class DenseVectorField extends FloatPointField {
+
+    static final String KNN_VECTOR_DIMENSION = "vectorDimension";
+    static final String KNN_SIMILARITY_FUNCTION = "similarityFunction";
+
+    int dimension;
+    VectorSimilarityFunction similarityFunction;
+    VectorSimilarityFunction DEFAULT_SIMILARITY = VectorSimilarityFunction.EUCLIDEAN;
+
+    @Override
+    public void init(IndexSchema schema, Map<String, String> args) {
+        this.dimension = ofNullable(args.get(KNN_VECTOR_DIMENSION))
+                .map(value -> parseDimensionParameter(value))
+                .orElseThrow(() -> new SolrException(SolrException.ErrorCode.SERVER_ERROR, "the vector dimension is a mandatory parameter"));
+        args.remove(KNN_VECTOR_DIMENSION);
+
+        this.similarityFunction = ofNullable(args.get(KNN_SIMILARITY_FUNCTION))
+                .map(value -> VectorSimilarityFunction.valueOf(value.toUpperCase(Locale.ROOT)))
+                .orElse(DEFAULT_SIMILARITY);
+        args.remove(KNN_SIMILARITY_FUNCTION);
+
+        this.properties &= ~MULTIVALUED;
+        this.properties &= ~UNINVERTIBLE;
+        
+        super.init(schema, args);
+    }
+
+    private int parseDimensionParameter(String value) {
+        try {
+            return Integer.parseInt(value);
+        } catch (NumberFormatException e) {
+            throw new SolrException(SolrException.ErrorCode.SERVER_ERROR, "the vector dimension must be an integer");
+        }
+    }
+
+    public int getDimension() {
+        return dimension;
+    }
+
+    @Override
+    public void checkSchemaField(final SchemaField field) throws SolrException {
+        super.checkSchemaField(field);
+        if (field.multiValued()) {
+            throw new SolrException(SolrException.ErrorCode.SERVER_ERROR,
+                    getClass().getSimpleName() + " fields can not be multiValued: " + field.getName());
+        }

Review comment:
       Is there a ticket for tracking this? Curious if/what the lucene-side blockers are 




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880: K Nearest Neighbors Search

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r787652410



##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not be solved simply by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+
+=== DenseVectorField
+The Dense Vector field gives the possibility of indexing and searching dense vectors of float elements.
+
+e.g.
+
+`[1.0, 2.5, 3.7, 4.1]` (array of float elements)
+
+Here's how `DenseVectorField` should be configured in the schema:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`vectorDimension`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The dimension of the dense vector to pass in.
++
+Accepted values:
+Integer < = 1024.
+
+`similarityFunction`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `euclidean`
+|===
++
+Vector similarity function; used in search to return top K most similar vectors to a target vector.
++
+Accepted values: `euclidean`, `dot_product`  or `cosine`.
+
+* `euclidean`: https://en.wikipedia.org/wiki/Euclidean_distance[Euclidean distance]
+* `dot_product`: https://en.wikipedia.org/wiki/Dot_product[Dot product]. *NOTE*: this similarity is intended as an optimized way to perform cosine similarity. In order to use it, all vectors must be of unit length, including both document and query vectors. Using dot product with vectors that are not unit length can result in errors or poor search results..
+* `cosine`: https://en.wikipedia.org/wiki/Cosine_similarity[Cosine similarity]. *NOTE*: the preferred way to perform cosine similarity is to normalize all vectors to unit length, and instead use DOT_PRODUCT. You should only use this function if you need to preserve the original vectors and cannot normalize them in advance.
+
+*N.B.* To use the following advanced parameters that customise the codec format
+and the hyper-parameter of the HNSW algorithm make sure you set this configuration in the solrconfig.xml:
+[source,xml]
+<config>
+<codecFactory class="solr.SchemaCodecFactory"/>
+...
+
+Here's how `DenseVectorField` can be configured with the advanced codec hyper-parameters:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine" codecFormat="Lucene90HnswVectorsFormat" hnswMaxConnections="10" hnswBeamWidth="40"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`codecFormat`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `Lucene90HnswVectorsFormat`
+|===
++
+(advanced) Specifies the knn codec implementation to use
++
+
+Accepted values: `Lucene90HnswVectorsFormat`.
+
+Please note that the `codecFormat` accepted values may change in future releases.
+
+
+
+[NOTE]
+Lucene index back-compatibility is only supported for the default codec.
+If you choose to customize the `codecFormat` in your schema, upgrading to a future version of Solr may require you to either switch back to the default codec and optimize your index to rewrite it into the default codec before upgrading, or re-build your entire index from scratch after upgrading.
+
+`hnswMaxConnections`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 16
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+Controls how many of the nearest neighbor candidates are connected to the new node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `M` from the later paper.
++
+Accepted values:
+Integer.

Review comment:
       Done!




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880: K Nearest Neighbors Search

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r787630194



##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not be solved simply by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+

Review comment:
       Done!




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880: K Nearest Neighbors Search

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r787661683



##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not be solved simply by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+
+=== DenseVectorField
+The Dense Vector field gives the possibility of indexing and searching dense vectors of float elements.
+
+e.g.
+
+`[1.0, 2.5, 3.7, 4.1]` (array of float elements)
+
+Here's how `DenseVectorField` should be configured in the schema:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`vectorDimension`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The dimension of the dense vector to pass in.
++
+Accepted values:
+Integer < = 1024.
+
+`similarityFunction`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `euclidean`
+|===
++
+Vector similarity function; used in search to return top K most similar vectors to a target vector.
++
+Accepted values: `euclidean`, `dot_product`  or `cosine`.
+
+* `euclidean`: https://en.wikipedia.org/wiki/Euclidean_distance[Euclidean distance]
+* `dot_product`: https://en.wikipedia.org/wiki/Dot_product[Dot product]. *NOTE*: this similarity is intended as an optimized way to perform cosine similarity. In order to use it, all vectors must be of unit length, including both document and query vectors. Using dot product with vectors that are not unit length can result in errors or poor search results..
+* `cosine`: https://en.wikipedia.org/wiki/Cosine_similarity[Cosine similarity]. *NOTE*: the preferred way to perform cosine similarity is to normalize all vectors to unit length, and instead use DOT_PRODUCT. You should only use this function if you need to preserve the original vectors and cannot normalize them in advance.
+
+*N.B.* To use the following advanced parameters that customise the codec format
+and the hyper-parameter of the HNSW algorithm make sure you set this configuration in the solrconfig.xml:
+[source,xml]
+<config>
+<codecFactory class="solr.SchemaCodecFactory"/>
+...
+
+Here's how `DenseVectorField` can be configured with the advanced codec hyper-parameters:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine" codecFormat="Lucene90HnswVectorsFormat" hnswMaxConnections="10" hnswBeamWidth="40"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`codecFormat`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `Lucene90HnswVectorsFormat`
+|===
++
+(advanced) Specifies the knn codec implementation to use
++
+
+Accepted values: `Lucene90HnswVectorsFormat`.
+
+Please note that the `codecFormat` accepted values may change in future releases.
+
+
+
+[NOTE]
+Lucene index back-compatibility is only supported for the default codec.
+If you choose to customize the `codecFormat` in your schema, upgrading to a future version of Solr may require you to either switch back to the default codec and optimize your index to rewrite it into the default codec before upgrading, or re-build your entire index from scratch after upgrading.
+
+`hnswMaxConnections`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 16
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+Controls how many of the nearest neighbor candidates are connected to the new node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `M` from the later paper.
++
+Accepted values:
+Integer.
+
+`hnswBeamWidth`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 100
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+It is the number of nearest neighbor candidates to track while searching the graph for each newly inserted node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `efConstruction` from the later paper.
++
+Accepted values:
+Integer.
+
+DenseVectorField supports the attributes: `indexed`, `stored`.
+
+*N.B.* currently multivalue is not supported
+
+Here's how a `DenseVectorField` should be indexed:
+
+[.dynamic-tabs]
+--
+[example.tab-pane#json]
+====
+[.tab-label]*JSON*
+[source,json]
+----
+[{ "id": "1",
+"vector": [1.0, 2.5, 3.7, 4.1]
+},
+{ "id": "2",
+"vector": [1.5, 5.5, 6.7, 65.1]
+}
+]
+----
+====
+
+[example.tab-pane#xml]
+====
+[.tab-label]*XML*
+[source,xml]
+----
+<add>
+<doc>
+<field name="id">1</field>
+<field name="vector">1.0</field>
+<field name="vector">2.5</field>
+<field name="vector">3.7</field>
+<field name="vector">4.1</field>
+</doc>
+<doc>
+<field name="id">2</field>
+<field name="vector">1.5</field>
+<field name="vector">5.5</field>
+<field name="vector">6.7</field>
+<field name="vector">65.1</field>
+</doc>
+</add>
+----
+====
+
+[example.tab-pane#solrj]
+====
+[.tab-label]*SolrJ*
+[source,java,indent=0]
+----
+final SolrClient client = getSolrClient();
+
+final SolrInputDocument d1 = new SolrInputDocument();
+d1.setField("id", "1");
+d1.setField("vector", Arrays.asList(1.0f, 2.5f, 3.7f, 4.1f));
+
+
+final SolrInputDocument d2 = new SolrInputDocument();
+d2.setField("id", "2");
+d2.setField("vector", Arrays.asList(1.5f, 5.5f, 6.7f, 65.1f));
+
+client.add(Arrays.asList(d1, d2));
+----
+====
+--
+
+== Query Time
+This is the list of Apache Solr query approaches designed to support Neural Search:
+
+=== knn Query Parser
+The `knn` K-Nearest Neighbors query parser allows to find the k-nearest documents to the target vector according to indexed dense vectors in the given field.
+
+The score for a retrieved document is the approximate distance to the target vector(defined by the similarityFunction configured at indexing time).
+
+It takes the following parameters:
+
+`f`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The DenseVectorField to search in.
+
+`topK`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 10
+|===
++
+How many k-nearest results to return.

Review comment:
       Normalised to k-nearest




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880: K Nearest Neighbors Search

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r787634283



##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not be solved simply by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+

Review comment:
       Done!




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on pull request #476: SOLR-15880: K Nearest Neighbors Search

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on pull request #476:
URL: https://github.com/apache/solr/pull/476#issuecomment-1015606008


   > Thanks, @cpoerschke for the thoughtful review, I committed all your suggestions!
   
   And the most recent pass as well :)


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r776774674



##########
File path: solr/core/src/java/org/apache/solr/schema/DenseVectorField.java
##########
@@ -0,0 +1,200 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.solr.schema;
+
+import org.apache.lucene.document.KnnVectorField;
+import org.apache.lucene.document.StoredField;
+import org.apache.lucene.index.IndexableField;
+import org.apache.lucene.index.VectorSimilarityFunction;
+import org.apache.lucene.queries.function.ValueSource;
+import org.apache.lucene.search.KnnVectorQuery;
+import org.apache.lucene.search.Query;
+import org.apache.lucene.search.SortField;
+import org.apache.solr.common.SolrException;
+import org.apache.solr.response.TextResponseWriter;
+import org.apache.solr.search.QParser;
+import org.apache.solr.uninverting.UninvertingReader;
+
+import java.io.IOException;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
+
+import static java.util.Optional.ofNullable;
+
+/**
+ * Provides a field type to support Lucene's {@link
+ * org.apache.lucene.document.KnnVectorField}.
+ * See {@link org.apache.lucene.search.KnnVectorQuery} for more details.
+ * It supports a fixed cardinality dimension for the vector and a fixed similarity function.
+ * The default similarity is EUCLIDEAN_HNSW (L2).
+ * See subclasses for details.
+ *
+ * <br>
+ * Only {@code Indexed} and {@code Stored} attributes are supported.
+ */
+public class DenseVectorField extends FieldType {
+
+    static final String KNN_VECTOR_DIMENSION = "vectorDimension";
+    static final String KNN_SIMILARITY_FUNCTION = "similarityFunction";
+    
+    int dimension;
+    VectorSimilarityFunction similarityFunction;
+    VectorSimilarityFunction DEFAULT_SIMILARITY = VectorSimilarityFunction.EUCLIDEAN;
+
+    @Override
+    public void init(IndexSchema schema, Map<String, String> args){
+        this.dimension = ofNullable(args.get(KNN_VECTOR_DIMENSION))
+                .map(value -> parseDimensionParameter(value))
+                .orElseThrow(() -> new SolrException(SolrException.ErrorCode.SERVER_ERROR, "the vector dimension is a mandatory parameter"));
+        args.remove(KNN_VECTOR_DIMENSION);
+
+        this.similarityFunction = ofNullable(args.get(KNN_SIMILARITY_FUNCTION))
+                .map(value -> VectorSimilarityFunction.valueOf(value.toUpperCase(Locale.ROOT)))
+                .orElse(DEFAULT_SIMILARITY);
+        args.remove(KNN_SIMILARITY_FUNCTION);
+
+        this.properties &= ~MULTIVALUED;
+        this.properties &= ~UNINVERTIBLE;
+        
+        super.init(schema, args);
+    }
+
+    private int parseDimensionParameter(String value) {
+        try {
+            return Integer.parseInt(value);
+        } catch (NumberFormatException e) {
+            throw new SolrException(SolrException.ErrorCode.SERVER_ERROR, "the vector dimension must be an integer");
+        }
+    }
+
+    @Override
+    public void checkSchemaField(final SchemaField field) throws SolrException {
+        super.checkSchemaField(field);
+        if (field.multiValued()) {
+            throw new SolrException(SolrException.ErrorCode.SERVER_ERROR,
+                    getClass().getSimpleName() + " fields can not be multiValued: " + field.getName());
+        }
+    }
+    
+    public List<IndexableField> createFields(SchemaField field, Object value) {
+        List<IndexableField> fields = new ArrayList<>();
+        if (field.indexed()){
+            fields.add(createField(field, value));
+        }
+        if (field.stored()){
+            fields.add(createStoredField(field, value));
+        }
+        return fields;
+    }
+
+    private IndexableField createStoredField(SchemaField field, Object value) {
+        return new StoredField(field.getName(), value.toString());
+    }
+
+    @Override
+    public UninvertingReader.Type getUninversionType(SchemaField sf) {
+        return null;
+    }
+
+    @Override
+    public ValueSource getValueSource(SchemaField field, QParser parser) {
+        throw new SolrException(SolrException.ErrorCode.BAD_REQUEST,
+                "Function queries are not supported for Dense Vector fields.");
+    }
+
+    @Override
+    public void write(TextResponseWriter writer, String name, IndexableField f) throws IOException {
+        writer.writeVal(name, f.stringValue());

Review comment:
       This should have been resolved with latest commit




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] sonatype-lift[bot] commented on a change in pull request #476: SOLR-15880

Posted by GitBox <gi...@apache.org>.
sonatype-lift[bot] commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r775006541



##########
File path: solr/core/src/java/org/apache/solr/schema/DenseVectorField.java
##########
@@ -0,0 +1,200 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.solr.schema;
+
+import org.apache.lucene.document.KnnVectorField;
+import org.apache.lucene.document.StoredField;
+import org.apache.lucene.index.IndexableField;
+import org.apache.lucene.index.VectorSimilarityFunction;
+import org.apache.lucene.queries.function.ValueSource;
+import org.apache.lucene.search.KnnVectorQuery;
+import org.apache.lucene.search.Query;
+import org.apache.lucene.search.SortField;
+import org.apache.solr.common.SolrException;
+import org.apache.solr.response.TextResponseWriter;
+import org.apache.solr.search.QParser;
+import org.apache.solr.uninverting.UninvertingReader;
+
+import java.io.IOException;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
+
+import static java.util.Optional.ofNullable;
+
+/**
+ * Provides a field type to support Lucene's {@link
+ * org.apache.lucene.document.KnnVectorField}.
+ * See {@link org.apache.lucene.search.KnnVectorQuery} for more details.
+ * It supports a fixed cardinality dimension for the vector and a fixed similarity function.
+ * The default similarity is EUCLIDEAN_HNSW (L2).
+ * See subclasses for details.
+ *
+ * <br>
+ * Only {@code Indexed} and {@code Stored} attributes are supported.
+ */
+public class DenseVectorField extends FieldType {
+
+    static final String KNN_VECTOR_DIMENSION = "vectorDimension";
+    static final String KNN_SIMILARITY_FUNCTION = "similarityFunction";
+    
+    int dimension;
+    VectorSimilarityFunction similarityFunction;
+    VectorSimilarityFunction DEFAULT_SIMILARITY = VectorSimilarityFunction.EUCLIDEAN;
+
+    @Override
+    public void init(IndexSchema schema, Map<String, String> args){
+        this.dimension = ofNullable(args.get(KNN_VECTOR_DIMENSION))
+                .map(value -> parseDimensionParameter(value))
+                .orElseThrow(() -> new SolrException(SolrException.ErrorCode.SERVER_ERROR, "the vector dimension is a mandatory parameter"));
+        args.remove(KNN_VECTOR_DIMENSION);
+
+        this.similarityFunction = ofNullable(args.get(KNN_SIMILARITY_FUNCTION))
+                .map(value -> VectorSimilarityFunction.valueOf(value.toUpperCase(Locale.ROOT)))
+                .orElse(DEFAULT_SIMILARITY);
+        args.remove(KNN_SIMILARITY_FUNCTION);
+
+        this.properties &= ~MULTIVALUED;
+        this.properties &= ~UNINVERTIBLE;
+        
+        super.init(schema, args);
+    }
+
+    private int parseDimensionParameter(String value) {
+        try {
+            return Integer.parseInt(value);
+        } catch (NumberFormatException e) {
+            throw new SolrException(SolrException.ErrorCode.SERVER_ERROR, "the vector dimension must be an integer");
+        }
+    }
+
+    @Override
+    public void checkSchemaField(final SchemaField field) throws SolrException {
+        super.checkSchemaField(field);
+        if (field.multiValued()) {
+            throw new SolrException(SolrException.ErrorCode.SERVER_ERROR,
+                    getClass().getSimpleName() + " fields can not be multiValued: " + field.getName());
+        }
+    }
+    
+    public List<IndexableField> createFields(SchemaField field, Object value) {
+        List<IndexableField> fields = new ArrayList<>();
+        if (field.indexed()){
+            fields.add(createField(field, value));
+        }
+        if (field.stored()){
+            fields.add(createStoredField(field, value));
+        }
+        return fields;
+    }
+
+    private IndexableField createStoredField(SchemaField field, Object value) {
+        return new StoredField(field.getName(), value.toString());
+    }
+
+    @Override
+    public UninvertingReader.Type getUninversionType(SchemaField sf) {
+        return null;
+    }
+
+    @Override
+    public ValueSource getValueSource(SchemaField field, QParser parser) {
+        throw new SolrException(SolrException.ErrorCode.BAD_REQUEST,
+                "Function queries are not supported for Dense Vector fields.");
+    }
+
+    @Override
+    public void write(TextResponseWriter writer, String name, IndexableField f) throws IOException {
+        writer.writeVal(name, f.stringValue());
+    }
+
+    @Override
+    public IndexableField createField(SchemaField field, Object value) {
+        float[] parsedVector;
+        try {
+            parsedVector = parseVector(value.toString());
+        } catch (RuntimeException e) {
+            throw new SolrException(SolrException.ErrorCode.SERVER_ERROR, "Error while creating field '" + field + "' from value '" + value + "', expected format:'[f1, f2, f3...fn]' e.g. [1.0, 3.4, 5.6]", e);
+        }
+        if (parsedVector == null) return null;
+
+        return new KnnVectorField(field.getName(), parsedVector, similarityFunction);
+    }
+
+    /**
+     * Parses a String vector.
+     *
+     * @param value with format: [f1, f2, f3, f4...fn]
+     * @return a float array
+     */
+    private float[] parseVector(String value) {
+        if (!value.startsWith("[") || !value.endsWith("]")) {
+            throw new SolrException(SolrException.ErrorCode.BAD_REQUEST, "incorrect vector format." +
+                    " The expected format is:'[f1,f2..f3]' where each element f is a float");
+        }
+        
+        String[] elements = value.substring(1, value.length() - 1).split(",");

Review comment:
       *StringSplitter:*  String.split(String) has surprising behavior [(details)](https://errorprone.info/bugpattern/StringSplitter)
   (at-me [in a reply](https://help.sonatype.com/lift/talking-to-lift) with `help` or `ignore`)




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] sonatype-lift[bot] commented on a change in pull request #476: SOLR-15880

Posted by GitBox <gi...@apache.org>.
sonatype-lift[bot] commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r776819890



##########
File path: solr/core/src/java/org/apache/solr/search/neural/KnnQParser.java
##########
@@ -0,0 +1,100 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.solr.search.neural;
+
+import org.apache.lucene.search.Query;
+import org.apache.solr.common.SolrException;
+import org.apache.solr.common.params.SolrParams;
+import org.apache.solr.request.SolrQueryRequest;
+import org.apache.solr.schema.DenseVectorField;
+import org.apache.solr.schema.FieldType;
+import org.apache.solr.schema.SchemaField;
+import org.apache.solr.search.QParser;
+import org.apache.solr.search.QueryParsing;
+
+public class KnnQParser extends QParser {
+
+    static final String TOP_K = "topK";// retrieve the top K results based on the distance similarity function 
+    static final int DEFAULT_TOP_K = 10;
+
+    /**
+     * Constructor for the QParser
+     *
+     * @param qstr        The part of the query string specific to this parser
+     * @param localParams The set of parameters that are specific to this QParser.  See https://solr.apache.org/guide/local-parameters-in-queries.html
+     * @param params      The rest of the {@link SolrParams}
+     * @param req         The original {@link SolrQueryRequest}.
+     */
+    public KnnQParser(String qstr, SolrParams localParams, SolrParams params, SolrQueryRequest req) {
+        super(qstr, localParams, params, req);
+    }
+
+    @Override
+    public Query parse() {
+        String denseVectorField = localParams.get(QueryParsing.F);
+        String vectorToSearch = localParams.get(QueryParsing.V);
+        int topK = localParams.getInt(TOP_K, DEFAULT_TOP_K);
+
+        if (denseVectorField == null || denseVectorField.isEmpty()) {
+            throw new SolrException(SolrException.ErrorCode.BAD_REQUEST, "the Dense Vector field 'f' is missing");
+        }
+
+        if (vectorToSearch == null || vectorToSearch.isEmpty()) {
+            throw new SolrException(SolrException.ErrorCode.BAD_REQUEST, "the Dense Vector to search is missing");
+        }
+
+        SchemaField schemaField = req.getCore().getLatestSchema().getField(denseVectorField);
+        FieldType fieldType = schemaField.getType();
+        if (!(fieldType instanceof DenseVectorField)) {
+            throw new SolrException(SolrException.ErrorCode.BAD_REQUEST, "only DenseVectorField is compatible with Knn Query Parser");
+        }
+
+        DenseVectorField denseVectorType = (DenseVectorField) fieldType;
+        float[] parsedVectorToSearch = parseVector(vectorToSearch, denseVectorType.getDimension());
+        return denseVectorType.getKnnVectorQuery(schemaField, parsedVectorToSearch, topK);
+    }
+
+    /**
+     * Parses a String vector.
+     *
+     * @param value with format: [f1, f2, f3, f4...fn]
+     * @return a float array
+     */
+    private float[] parseVector(String value, int dimension) {
+        if (!value.startsWith("[") || !value.endsWith("]")) {
+            throw new SolrException(SolrException.ErrorCode.BAD_REQUEST, "incorrect vector format." +
+                    " The expected format is:'[f1,f2..f3]' where each element f is a float");
+        }
+
+        String[] elements = value.substring(1, value.length() - 1).split(",");

Review comment:
       *StringSplitter:*  String.split(String) has surprising behavior [(details)](https://errorprone.info/bugpattern/StringSplitter)
   (at-me [in a reply](https://help.sonatype.com/lift/talking-to-lift) with `help` or `ignore`)




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] noblepaul commented on a change in pull request #476: SOLR-15880

Posted by GitBox <gi...@apache.org>.
noblepaul commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r780884950



##########
File path: solr/core/src/java/org/apache/solr/search/neural/KnnQParser.java
##########
@@ -0,0 +1,100 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.solr.search.neural;
+
+import org.apache.lucene.search.Query;
+import org.apache.solr.common.SolrException;
+import org.apache.solr.common.params.SolrParams;
+import org.apache.solr.request.SolrQueryRequest;
+import org.apache.solr.schema.DenseVectorField;
+import org.apache.solr.schema.FieldType;
+import org.apache.solr.schema.SchemaField;
+import org.apache.solr.search.QParser;
+import org.apache.solr.search.QueryParsing;
+
+public class KnnQParser extends QParser {
+
+    static final String TOP_K = "topK";// retrieve the top K results based on the distance similarity function 
+    static final int DEFAULT_TOP_K = 10;
+
+    /**
+     * Constructor for the QParser
+     *
+     * @param qstr        The part of the query string specific to this parser
+     * @param localParams The set of parameters that are specific to this QParser.  See https://solr.apache.org/guide/local-parameters-in-queries.html
+     * @param params      The rest of the {@link SolrParams}
+     * @param req         The original {@link SolrQueryRequest}.
+     */
+    public KnnQParser(String qstr, SolrParams localParams, SolrParams params, SolrQueryRequest req) {
+        super(qstr, localParams, params, req);
+    }
+
+    @Override
+    public Query parse() {
+        String denseVectorField = localParams.get(QueryParsing.F);
+        String vectorToSearch = localParams.get(QueryParsing.V);
+        int topK = localParams.getInt(TOP_K, DEFAULT_TOP_K);
+
+        if (denseVectorField == null || denseVectorField.isEmpty()) {
+            throw new SolrException(SolrException.ErrorCode.BAD_REQUEST, "the Dense Vector field 'f' is missing");
+        }
+
+        if (vectorToSearch == null || vectorToSearch.isEmpty()) {
+            throw new SolrException(SolrException.ErrorCode.BAD_REQUEST, "the Dense Vector to search is missing");
+        }
+
+        SchemaField schemaField = req.getCore().getLatestSchema().getField(denseVectorField);
+        FieldType fieldType = schemaField.getType();
+        if (!(fieldType instanceof DenseVectorField)) {
+            throw new SolrException(SolrException.ErrorCode.BAD_REQUEST, "only DenseVectorField is compatible with Knn Query Parser");
+        }
+
+        DenseVectorField denseVectorType = (DenseVectorField) fieldType;
+        float[] parsedVectorToSearch = parseVector(vectorToSearch, denseVectorType.getDimension());
+        return denseVectorType.getKnnVectorQuery(schemaField, parsedVectorToSearch, topK);
+    }
+
+    /**
+     * Parses a String vector.
+     *
+     * @param value with format: [f1, f2, f3, f4...fn]
+     * @return a float array
+     */
+    private float[] parseVector(String value, int dimension) {
+        if (!value.startsWith("[") || !value.endsWith("]")) {
+            throw new SolrException(SolrException.ErrorCode.BAD_REQUEST, "incorrect vector format." +
+                    " The expected format is:'[f1,f2..f3]' where each element f is a float");
+        }
+
+        String[] elements = value.substring(1, value.length() - 1).split(",");

Review comment:
       Please use `org.apache.commons.lang.Stringutils.split(String str, char separatorChar)`




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r786693763



##########
File path: solr/core/src/java/org/apache/solr/core/SchemaCodecFactory.java
##########
@@ -114,6 +117,25 @@ public DocValuesFormat getDocValuesFormatForField(String field) {
         }
         return super.getDocValuesFormatForField(field);
       }
+
+      @Override
+      public KnnVectorsFormat getKnnVectorsFormatForField(String field) {
+        final SchemaField schemaField = core.getLatestSchema().getFieldOrNull(field);
+        if (schemaField != null && schemaField.getType() instanceof DenseVectorField) {
+          DenseVectorField vectorType = (DenseVectorField) schemaField.getType();

Review comment:
       Done in a dedicated commit and included a null check! thanks!




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] cpoerschke commented on a change in pull request #476: SOLR-15880

Posted by GitBox <gi...@apache.org>.
cpoerschke commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r786178075



##########
File path: solr/core/src/java/org/apache/solr/core/SchemaCodecFactory.java
##########
@@ -114,6 +117,25 @@ public DocValuesFormat getDocValuesFormatForField(String field) {
         }
         return super.getDocValuesFormatForField(field);
       }
+
+      @Override
+      public KnnVectorsFormat getKnnVectorsFormatForField(String field) {
+        final SchemaField schemaField = core.getLatestSchema().getFieldOrNull(field);
+        if (schemaField != null && schemaField.getType() instanceof DenseVectorField) {
+          DenseVectorField vectorType = (DenseVectorField) schemaField.getType();

Review comment:
       minor: the following could avoid duplicate `schemaField.getType()` calls
   ```suggestion
           final FieldType fieldType = (schemaField == null ? null : schemaField.getType());
           if (fieldType instanceof DenseVectorField) {
             DenseVectorField vectorType = (DenseVectorField) fieldType;
   ```

##########
File path: solr/core/src/java/org/apache/solr/schema/DenseVectorField.java
##########
@@ -0,0 +1,256 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.solr.schema;
+
+import org.apache.lucene.codecs.lucene90.Lucene90HnswVectorsFormat;
+import org.apache.lucene.document.KnnVectorField;
+import org.apache.lucene.index.IndexableField;
+import org.apache.lucene.index.VectorSimilarityFunction;
+import org.apache.lucene.queries.function.ValueSource;
+import org.apache.lucene.search.KnnVectorQuery;
+import org.apache.lucene.search.Query;
+import org.apache.lucene.search.SortField;
+import org.apache.lucene.util.hnsw.HnswGraph;
+import org.apache.solr.common.SolrException;
+import org.apache.solr.search.QParser;
+import org.apache.solr.uninverting.UninvertingReader;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
+
+import static java.util.Optional.ofNullable;
+import static org.apache.lucene.codecs.lucene90.Lucene90HnswVectorsFormat.DEFAULT_BEAM_WIDTH;
+import static org.apache.lucene.codecs.lucene90.Lucene90HnswVectorsFormat.DEFAULT_MAX_CONN;
+
+/**
+ * Provides a field type to support Lucene's {@link
+ * org.apache.lucene.document.KnnVectorField}.
+ * See {@link org.apache.lucene.search.KnnVectorQuery} for more details.
+ * It supports a fixed cardinality dimension for the vector and a fixed similarity function.
+ * The default similarity is EUCLIDEAN_HNSW (L2).
+ * The default index codec format is specified in the Lucene Codec constructor.
+ * For Lucene 9.0 e.g.
+ * See {@link org.apache.lucene.codecs.lucene90.Lucene90Codec}
+ * Currently only {@link org.apache.lucene.codecs.lucene90.Lucene90HnswVectorsFormat} is supported for
+ * advanced hyper-parameter customisation.
+ * See {@link org.apache.lucene.util.hnsw.HnswGraph} for more details about the implementation. 
+ *
+ * <br>
+ * Only {@code Indexed} and {@code Stored} attributes are supported.
+ */
+public class DenseVectorField extends FloatPointField {
+
+    static final String KNN_VECTOR_DIMENSION = "vectorDimension";
+    static final String KNN_SIMILARITY_FUNCTION = "similarityFunction";
+    
+    static final String CODEC_FORMAT = "codecFormat";
+    static final String HNSW_MAX_CONNECTIONS = "hnswMaxConnections";
+    static final String HNSW_BEAM_WIDTH = "hnswBeamWidth";
+
+    int dimension;
+    VectorSimilarityFunction similarityFunction;
+    VectorSimilarityFunction DEFAULT_SIMILARITY = VectorSimilarityFunction.EUCLIDEAN;
+
+    String codecFormat;
+    /**
+     * This parameter is coupled with the {@link Lucene90HnswVectorsFormat} format implementation.
+     * Controls how many of the nearest neighbor candidates are connected to the new node. Defaults to
+     * {@link Lucene90HnswVectorsFormat#DEFAULT_MAX_CONN}. See {@link HnswGraph} for more details.
+     */
+    int hnswMaxConn;
+    /**
+     * This parameter is coupled with the {@link Lucene90HnswVectorsFormat} format implementation.
+     * The number of candidate neighbors to track while searching the graph for each newly inserted
+     * node. Defaults to to {@link Lucene90HnswVectorsFormat#DEFAULT_BEAM_WIDTH}. See {@link
+     * HnswGraph} for details.
+     */
+    int hnswBeamWidth;
+
+    @Override
+    public void init(IndexSchema schema, Map<String, String> args) {
+        this.dimension = ofNullable(args.get(KNN_VECTOR_DIMENSION))
+                .map(value -> Integer.parseInt(value))
+                .orElseThrow(() -> new SolrException(SolrException.ErrorCode.SERVER_ERROR, "the vector dimension is a mandatory parameter"));
+        args.remove(KNN_VECTOR_DIMENSION);
+
+        this.similarityFunction = ofNullable(args.get(KNN_SIMILARITY_FUNCTION))
+                .map(value -> VectorSimilarityFunction.valueOf(value.toUpperCase(Locale.ROOT)))
+                .orElse(DEFAULT_SIMILARITY);
+        args.remove(KNN_SIMILARITY_FUNCTION);
+
+        this.codecFormat = args.get(CODEC_FORMAT);
+        args.remove(CODEC_FORMAT);
+
+        this.hnswMaxConn = ofNullable(args.get(HNSW_MAX_CONNECTIONS))
+                .map(value -> Integer.parseInt(value))
+                .orElse(DEFAULT_MAX_CONN);
+        args.remove(HNSW_MAX_CONNECTIONS);
+
+        this.hnswBeamWidth = ofNullable(args.get(HNSW_BEAM_WIDTH))
+                .map(value -> Integer.parseInt(value))
+                .orElse(DEFAULT_BEAM_WIDTH);
+        args.remove(HNSW_BEAM_WIDTH);
+
+        this.properties &= ~MULTIVALUED;
+        this.properties &= ~UNINVERTIBLE;
+        
+        super.init(schema, args);
+    }
+
+    public int getDimension() {
+        return dimension;
+    }
+
+    public String getCodecFormat() {
+        return codecFormat;
+    }
+
+    public Integer getHnswMaxConn() {
+        return hnswMaxConn;
+    }
+
+    public Integer getHnswBeamWidth() {
+        return hnswBeamWidth;
+    }
+
+    @Override
+    public void checkSchemaField(final SchemaField field) throws SolrException {
+        super.checkSchemaField(field);
+        if (field.multiValued()) {
+            throw new SolrException(SolrException.ErrorCode.SERVER_ERROR,
+                    getClass().getSimpleName() + " fields can not be multiValued: " + field.getName());
+        }
+
+        if (field.hasDocValues()) {
+            throw new SolrException(SolrException.ErrorCode.SERVER_ERROR,
+                    getClass().getSimpleName() + " fields can not have docValues: " + field.getName());
+        }
+    }
+    
+    public List<IndexableField> createFields(SchemaField field, Object value) {
+        List<IndexableField> fields = new ArrayList<>();
+        float[] parsedVector;
+        try {
+            parsedVector = parseVector(value);
+        } catch (RuntimeException e) {
+            throw new SolrException(SolrException.ErrorCode.SERVER_ERROR, "Error while creating field '" + field + "' from value '" + value + "', expected format:'[f1, f2, f3...fn]' e.g. [1.0, 3.4, 5.6]", e);
+        }
+
+        if (field.indexed()) {
+            fields.add(createField(field, parsedVector));
+        }
+        if (field.stored()) {
+            for (float vectorElement : parsedVector) {
+                fields.add(getStoredField(field, vectorElement));
+            }
+        }
+        return fields;
+    }
+
+    @Override
+    public IndexableField createField(SchemaField field, Object parsedVector) {
+        float[] typedVector;
+        if (parsedVector == null) return null;
+        typedVector = (float[]) parsedVector;
+        return new KnnVectorField(field.getName(), typedVector, similarityFunction);
+    }
+
+    /**
+     * Index Time Parsing
+     * The inputValue is an ArrayList with a type that dipends on the loader used:
+     * - {@link org.apache.solr.handler.loader.XMLLoader}, {@link org.apache.solr.handler.loader.CSVLoader} produces an ArrayList of String
+     * - {@link org.apache.solr.handler.loader.JsonLoader} produces an ArrayList of Double
+     * - {@link org.apache.solr.handler.loader.JavabinLoader} produces an ArrayList of Float
+     *
+     * @param inputValue - An {@link ArrayList} containing the elements of the vector
+     * @return the vector parsed
+     */
+    float[] parseVector(Object inputValue) {
+        if (!(inputValue instanceof List)) {
+            throw new SolrException(SolrException.ErrorCode.BAD_REQUEST, "incorrect vector format." +
+                    " The expected format is an array :'[f1,f2..f3]' where each element f is a float");
+        }
+        List<?> inputVector = (List<?>) inputValue;
+        if (inputVector.size() != dimension) {
+            throw new SolrException(SolrException.ErrorCode.BAD_REQUEST, "incorrect vector dimension." +
+                    " The vector value has size "
+                    + inputVector.size() + " while it is expected a vector with size " + dimension);
+        }
+
+        float[] vector = new float[dimension];
+        if (inputVector.get(0) instanceof CharSequence) {
+            for (int i = 0; i < dimension; i++) {
+                try {
+                    vector[i] = Float.parseFloat(inputVector.get(i).toString());
+                } catch (NumberFormatException e) {
+                    throw new SolrException(SolrException.ErrorCode.BAD_REQUEST, "incorrect vector element: '" + inputVector.get(i) +
+                            "'. The expected format is:'[f1,f2..f3]' where each element f is a float");
+                }
+            }
+        } else if (inputVector.get(0) instanceof Number) {
+            for (int i = 0; i < dimension; i++) {
+                vector[i] = ((Number) inputVector.get(i)).floatValue();
+            }
+        }

Review comment:
       should this throw also or could we have a comment re: that/why it's okay to just return default vector?
   ```suggestion
           } else {
               throw new SolrException(...)
           }
   ```

##########
File path: solr/core/src/java/org/apache/solr/update/DocumentBuilder.java
##########
@@ -151,63 +153,49 @@ public static Document toDocument(SolrInputDocument doc, IndexSchema schema, boo
 
       String name = field.getName();
       SchemaField sfield = schema.getFieldOrNull(name);
-      boolean used = false;
       
+      List<CopyField> copyFields = schema.getCopyFieldsList(name);
+      if( copyFields.size() == 0 ) copyFields = null;

Review comment:
       ```suggestion
         if( copyFields.isEmpty() ) copyFields = null;
   ```

##########
File path: solr/core/src/java/org/apache/solr/update/DocumentBuilder.java
##########
@@ -258,6 +246,48 @@ public static Document toDocument(SolrInputDocument doc, IndexSchema schema, boo
     return out;
   }
 
+  private static boolean addOriginalField( Object originalFieldValue, SchemaField sfield, boolean forInPlaceUpdate, Document out, Set<String> usedFields) {
+    addField(out, sfield, originalFieldValue, forInPlaceUpdate);
+    // record the field as having a value
+    usedFields.add(sfield.getName());
+    return true;
+  }
+
+  private static boolean addCopyFields(Object originalFieldValue, FieldType originalFieldType, List<CopyField> copyFields, boolean forInPlaceUpdate, String uniqueKeyFieldName, Document out, Set<String> usedFields) {
+    boolean used = false;
+    for (CopyField cf : copyFields) {
+      SchemaField destinationField = cf.getDestination();
+
+      final boolean destHasValues = usedFields.contains(destinationField.getName());
+
+      // Dense Vector Fields can only be copied to same field type
+      if (originalFieldType instanceof DenseVectorField && !(destinationField.getType() instanceof DenseVectorField)) {
+        throw new SolrException(SolrException.ErrorCode.BAD_REQUEST,
+                "The copy field destination must be a DenseVectorField: " +
+                        destinationField.getName());
+      }

Review comment:
       Is there also a requirement for dimension alignment i.e. `dst` must not be higher dimension than `src` and/or they should be equal? Maybe that's already covered elsewhere, I haven't looked.

##########
File path: solr/core/src/test-files/solr/collection1/conf/bad-schema-densevector-docvalues.xml
##########
@@ -0,0 +1,31 @@
+<?xml version="1.0" ?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements.  See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License.  You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<!-- Test schema file for DenseVectorField -->
+
+<schema name="bad-schema-densevector-similarity-null" version="1.0">

Review comment:
       possibly unintended name attribute vs. file name mismatch
   ```suggestion
   <schema name="bad-schema-densevector-docvalues" version="1.0">
   ```

##########
File path: solr/core/src/java/org/apache/solr/search/neural/KnnQParser.java
##########
@@ -0,0 +1,101 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.solr.search.neural;
+
+import org.apache.commons.lang3.StringUtils;
+import org.apache.lucene.search.Query;
+import org.apache.solr.common.SolrException;
+import org.apache.solr.common.params.SolrParams;
+import org.apache.solr.request.SolrQueryRequest;
+import org.apache.solr.schema.DenseVectorField;
+import org.apache.solr.schema.FieldType;
+import org.apache.solr.schema.SchemaField;
+import org.apache.solr.search.QParser;
+import org.apache.solr.search.QueryParsing;
+
+public class KnnQParser extends QParser {
+
+    static final String TOP_K = "topK";// retrieve the top K results based on the distance similarity function 
+    static final int DEFAULT_TOP_K = 10;
+
+    /**
+     * Constructor for the QParser
+     *
+     * @param qstr        The part of the query string specific to this parser
+     * @param localParams The set of parameters that are specific to this QParser.  See https://solr.apache.org/guide/local-parameters-in-queries.html
+     * @param params      The rest of the {@link SolrParams}
+     * @param req         The original {@link SolrQueryRequest}.
+     */
+    public KnnQParser(String qstr, SolrParams localParams, SolrParams params, SolrQueryRequest req) {
+        super(qstr, localParams, params, req);
+    }
+
+    @Override
+    public Query parse() {
+        String denseVectorField = localParams.get(QueryParsing.F);
+        String vectorToSearch = localParams.get(QueryParsing.V);
+        int topK = localParams.getInt(TOP_K, DEFAULT_TOP_K);
+
+        if (denseVectorField == null || denseVectorField.isEmpty()) {
+            throw new SolrException(SolrException.ErrorCode.BAD_REQUEST, "the Dense Vector field 'f' is missing");
+        }
+
+        if (vectorToSearch == null || vectorToSearch.isEmpty()) {
+            throw new SolrException(SolrException.ErrorCode.BAD_REQUEST, "the Dense Vector to search is missing");
+        }
+
+        SchemaField schemaField = req.getCore().getLatestSchema().getField(denseVectorField);
+        FieldType fieldType = schemaField.getType();
+        if (!(fieldType instanceof DenseVectorField)) {
+            throw new SolrException(SolrException.ErrorCode.BAD_REQUEST, "only DenseVectorField is compatible with Knn Query Parser");
+        }
+
+        DenseVectorField denseVectorType = (DenseVectorField) fieldType;
+        float[] parsedVectorToSearch = parseVector(vectorToSearch, denseVectorType.getDimension());
+        return denseVectorType.getKnnVectorQuery(schemaField, parsedVectorToSearch, topK);
+    }
+
+    /**
+     * Parses a String vector.
+     *
+     * @param value with format: [f1, f2, f3, f4...fn]
+     * @return a float array
+     */
+    private float[] parseVector(String value, int dimension) {

Review comment:
       ```suggestion
       static private float[] parseVector(String value, int dimension) {
   ```

##########
File path: solr/core/src/java/org/apache/solr/schema/DenseVectorField.java
##########
@@ -0,0 +1,256 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.solr.schema;
+
+import org.apache.lucene.codecs.lucene90.Lucene90HnswVectorsFormat;
+import org.apache.lucene.document.KnnVectorField;
+import org.apache.lucene.index.IndexableField;
+import org.apache.lucene.index.VectorSimilarityFunction;
+import org.apache.lucene.queries.function.ValueSource;
+import org.apache.lucene.search.KnnVectorQuery;
+import org.apache.lucene.search.Query;
+import org.apache.lucene.search.SortField;
+import org.apache.lucene.util.hnsw.HnswGraph;
+import org.apache.solr.common.SolrException;
+import org.apache.solr.search.QParser;
+import org.apache.solr.uninverting.UninvertingReader;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
+
+import static java.util.Optional.ofNullable;
+import static org.apache.lucene.codecs.lucene90.Lucene90HnswVectorsFormat.DEFAULT_BEAM_WIDTH;
+import static org.apache.lucene.codecs.lucene90.Lucene90HnswVectorsFormat.DEFAULT_MAX_CONN;
+
+/**
+ * Provides a field type to support Lucene's {@link
+ * org.apache.lucene.document.KnnVectorField}.
+ * See {@link org.apache.lucene.search.KnnVectorQuery} for more details.
+ * It supports a fixed cardinality dimension for the vector and a fixed similarity function.
+ * The default similarity is EUCLIDEAN_HNSW (L2).
+ * The default index codec format is specified in the Lucene Codec constructor.
+ * For Lucene 9.0 e.g.
+ * See {@link org.apache.lucene.codecs.lucene90.Lucene90Codec}
+ * Currently only {@link org.apache.lucene.codecs.lucene90.Lucene90HnswVectorsFormat} is supported for
+ * advanced hyper-parameter customisation.
+ * See {@link org.apache.lucene.util.hnsw.HnswGraph} for more details about the implementation. 
+ *
+ * <br>
+ * Only {@code Indexed} and {@code Stored} attributes are supported.
+ */
+public class DenseVectorField extends FloatPointField {
+
+    static final String KNN_VECTOR_DIMENSION = "vectorDimension";
+    static final String KNN_SIMILARITY_FUNCTION = "similarityFunction";
+    
+    static final String CODEC_FORMAT = "codecFormat";
+    static final String HNSW_MAX_CONNECTIONS = "hnswMaxConnections";
+    static final String HNSW_BEAM_WIDTH = "hnswBeamWidth";
+
+    int dimension;
+    VectorSimilarityFunction similarityFunction;
+    VectorSimilarityFunction DEFAULT_SIMILARITY = VectorSimilarityFunction.EUCLIDEAN;
+
+    String codecFormat;
+    /**
+     * This parameter is coupled with the {@link Lucene90HnswVectorsFormat} format implementation.
+     * Controls how many of the nearest neighbor candidates are connected to the new node. Defaults to
+     * {@link Lucene90HnswVectorsFormat#DEFAULT_MAX_CONN}. See {@link HnswGraph} for more details.
+     */
+    int hnswMaxConn;
+    /**
+     * This parameter is coupled with the {@link Lucene90HnswVectorsFormat} format implementation.
+     * The number of candidate neighbors to track while searching the graph for each newly inserted
+     * node. Defaults to to {@link Lucene90HnswVectorsFormat#DEFAULT_BEAM_WIDTH}. See {@link
+     * HnswGraph} for details.
+     */
+    int hnswBeamWidth;
+
+    @Override
+    public void init(IndexSchema schema, Map<String, String> args) {
+        this.dimension = ofNullable(args.get(KNN_VECTOR_DIMENSION))
+                .map(value -> Integer.parseInt(value))
+                .orElseThrow(() -> new SolrException(SolrException.ErrorCode.SERVER_ERROR, "the vector dimension is a mandatory parameter"));
+        args.remove(KNN_VECTOR_DIMENSION);
+
+        this.similarityFunction = ofNullable(args.get(KNN_SIMILARITY_FUNCTION))
+                .map(value -> VectorSimilarityFunction.valueOf(value.toUpperCase(Locale.ROOT)))
+                .orElse(DEFAULT_SIMILARITY);
+        args.remove(KNN_SIMILARITY_FUNCTION);
+
+        this.codecFormat = args.get(CODEC_FORMAT);
+        args.remove(CODEC_FORMAT);
+
+        this.hnswMaxConn = ofNullable(args.get(HNSW_MAX_CONNECTIONS))
+                .map(value -> Integer.parseInt(value))
+                .orElse(DEFAULT_MAX_CONN);
+        args.remove(HNSW_MAX_CONNECTIONS);
+
+        this.hnswBeamWidth = ofNullable(args.get(HNSW_BEAM_WIDTH))
+                .map(value -> Integer.parseInt(value))
+                .orElse(DEFAULT_BEAM_WIDTH);
+        args.remove(HNSW_BEAM_WIDTH);
+
+        this.properties &= ~MULTIVALUED;
+        this.properties &= ~UNINVERTIBLE;
+        
+        super.init(schema, args);
+    }
+
+    public int getDimension() {
+        return dimension;
+    }
+
+    public String getCodecFormat() {
+        return codecFormat;
+    }
+
+    public Integer getHnswMaxConn() {
+        return hnswMaxConn;
+    }
+
+    public Integer getHnswBeamWidth() {
+        return hnswBeamWidth;
+    }
+
+    @Override
+    public void checkSchemaField(final SchemaField field) throws SolrException {
+        super.checkSchemaField(field);
+        if (field.multiValued()) {
+            throw new SolrException(SolrException.ErrorCode.SERVER_ERROR,
+                    getClass().getSimpleName() + " fields can not be multiValued: " + field.getName());
+        }
+
+        if (field.hasDocValues()) {
+            throw new SolrException(SolrException.ErrorCode.SERVER_ERROR,
+                    getClass().getSimpleName() + " fields can not have docValues: " + field.getName());
+        }
+    }
+    
+    public List<IndexableField> createFields(SchemaField field, Object value) {
+        List<IndexableField> fields = new ArrayList<>();
+        float[] parsedVector;
+        try {
+            parsedVector = parseVector(value);
+        } catch (RuntimeException e) {
+            throw new SolrException(SolrException.ErrorCode.SERVER_ERROR, "Error while creating field '" + field + "' from value '" + value + "', expected format:'[f1, f2, f3...fn]' e.g. [1.0, 3.4, 5.6]", e);
+        }
+
+        if (field.indexed()) {
+            fields.add(createField(field, parsedVector));
+        }
+        if (field.stored()) {
+            for (float vectorElement : parsedVector) {
+                fields.add(getStoredField(field, vectorElement));
+            }
+        }
+        return fields;
+    }
+
+    @Override
+    public IndexableField createField(SchemaField field, Object parsedVector) {
+        float[] typedVector;
+        if (parsedVector == null) return null;
+        typedVector = (float[]) parsedVector;

Review comment:
       ```suggestion
           if (parsedVector == null) return null;
           float[] typedVector = (float[]) parsedVector;
   ```

##########
File path: solr/core/src/java/org/apache/solr/search/neural/KnnQParser.java
##########
@@ -0,0 +1,101 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.solr.search.neural;
+
+import org.apache.commons.lang3.StringUtils;
+import org.apache.lucene.search.Query;
+import org.apache.solr.common.SolrException;
+import org.apache.solr.common.params.SolrParams;
+import org.apache.solr.request.SolrQueryRequest;
+import org.apache.solr.schema.DenseVectorField;
+import org.apache.solr.schema.FieldType;
+import org.apache.solr.schema.SchemaField;
+import org.apache.solr.search.QParser;
+import org.apache.solr.search.QueryParsing;
+
+public class KnnQParser extends QParser {
+
+    static final String TOP_K = "topK";// retrieve the top K results based on the distance similarity function 
+    static final int DEFAULT_TOP_K = 10;
+
+    /**
+     * Constructor for the QParser
+     *
+     * @param qstr        The part of the query string specific to this parser
+     * @param localParams The set of parameters that are specific to this QParser.  See https://solr.apache.org/guide/local-parameters-in-queries.html
+     * @param params      The rest of the {@link SolrParams}
+     * @param req         The original {@link SolrQueryRequest}.
+     */
+    public KnnQParser(String qstr, SolrParams localParams, SolrParams params, SolrQueryRequest req) {
+        super(qstr, localParams, params, req);
+    }
+
+    @Override
+    public Query parse() {
+        String denseVectorField = localParams.get(QueryParsing.F);
+        String vectorToSearch = localParams.get(QueryParsing.V);
+        int topK = localParams.getInt(TOP_K, DEFAULT_TOP_K);
+
+        if (denseVectorField == null || denseVectorField.isEmpty()) {
+            throw new SolrException(SolrException.ErrorCode.BAD_REQUEST, "the Dense Vector field 'f' is missing");
+        }
+
+        if (vectorToSearch == null || vectorToSearch.isEmpty()) {
+            throw new SolrException(SolrException.ErrorCode.BAD_REQUEST, "the Dense Vector to search is missing");

Review comment:
       similar to `field 'f'` above could do `value 'v'` here too
   ```suggestion
               throw new SolrException(SolrException.ErrorCode.BAD_REQUEST, "the Dense Vector value 'v' to search is missing");
   ```

##########
File path: solr/core/src/java/org/apache/solr/schema/DenseVectorField.java
##########
@@ -0,0 +1,256 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.solr.schema;
+
+import org.apache.lucene.codecs.lucene90.Lucene90HnswVectorsFormat;
+import org.apache.lucene.document.KnnVectorField;
+import org.apache.lucene.index.IndexableField;
+import org.apache.lucene.index.VectorSimilarityFunction;
+import org.apache.lucene.queries.function.ValueSource;
+import org.apache.lucene.search.KnnVectorQuery;
+import org.apache.lucene.search.Query;
+import org.apache.lucene.search.SortField;
+import org.apache.lucene.util.hnsw.HnswGraph;
+import org.apache.solr.common.SolrException;
+import org.apache.solr.search.QParser;
+import org.apache.solr.uninverting.UninvertingReader;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
+
+import static java.util.Optional.ofNullable;
+import static org.apache.lucene.codecs.lucene90.Lucene90HnswVectorsFormat.DEFAULT_BEAM_WIDTH;
+import static org.apache.lucene.codecs.lucene90.Lucene90HnswVectorsFormat.DEFAULT_MAX_CONN;
+
+/**
+ * Provides a field type to support Lucene's {@link
+ * org.apache.lucene.document.KnnVectorField}.
+ * See {@link org.apache.lucene.search.KnnVectorQuery} for more details.
+ * It supports a fixed cardinality dimension for the vector and a fixed similarity function.
+ * The default similarity is EUCLIDEAN_HNSW (L2).
+ * The default index codec format is specified in the Lucene Codec constructor.
+ * For Lucene 9.0 e.g.
+ * See {@link org.apache.lucene.codecs.lucene90.Lucene90Codec}
+ * Currently only {@link org.apache.lucene.codecs.lucene90.Lucene90HnswVectorsFormat} is supported for
+ * advanced hyper-parameter customisation.
+ * See {@link org.apache.lucene.util.hnsw.HnswGraph} for more details about the implementation. 
+ *
+ * <br>
+ * Only {@code Indexed} and {@code Stored} attributes are supported.
+ */
+public class DenseVectorField extends FloatPointField {
+
+    static final String KNN_VECTOR_DIMENSION = "vectorDimension";
+    static final String KNN_SIMILARITY_FUNCTION = "similarityFunction";
+    
+    static final String CODEC_FORMAT = "codecFormat";
+    static final String HNSW_MAX_CONNECTIONS = "hnswMaxConnections";
+    static final String HNSW_BEAM_WIDTH = "hnswBeamWidth";
+
+    int dimension;
+    VectorSimilarityFunction similarityFunction;
+    VectorSimilarityFunction DEFAULT_SIMILARITY = VectorSimilarityFunction.EUCLIDEAN;
+
+    String codecFormat;
+    /**
+     * This parameter is coupled with the {@link Lucene90HnswVectorsFormat} format implementation.
+     * Controls how many of the nearest neighbor candidates are connected to the new node. Defaults to
+     * {@link Lucene90HnswVectorsFormat#DEFAULT_MAX_CONN}. See {@link HnswGraph} for more details.
+     */
+    int hnswMaxConn;
+    /**
+     * This parameter is coupled with the {@link Lucene90HnswVectorsFormat} format implementation.
+     * The number of candidate neighbors to track while searching the graph for each newly inserted
+     * node. Defaults to to {@link Lucene90HnswVectorsFormat#DEFAULT_BEAM_WIDTH}. See {@link
+     * HnswGraph} for details.
+     */
+    int hnswBeamWidth;
+
+    @Override
+    public void init(IndexSchema schema, Map<String, String> args) {
+        this.dimension = ofNullable(args.get(KNN_VECTOR_DIMENSION))
+                .map(value -> Integer.parseInt(value))
+                .orElseThrow(() -> new SolrException(SolrException.ErrorCode.SERVER_ERROR, "the vector dimension is a mandatory parameter"));
+        args.remove(KNN_VECTOR_DIMENSION);
+
+        this.similarityFunction = ofNullable(args.get(KNN_SIMILARITY_FUNCTION))
+                .map(value -> VectorSimilarityFunction.valueOf(value.toUpperCase(Locale.ROOT)))
+                .orElse(DEFAULT_SIMILARITY);
+        args.remove(KNN_SIMILARITY_FUNCTION);
+
+        this.codecFormat = args.get(CODEC_FORMAT);
+        args.remove(CODEC_FORMAT);
+
+        this.hnswMaxConn = ofNullable(args.get(HNSW_MAX_CONNECTIONS))
+                .map(value -> Integer.parseInt(value))
+                .orElse(DEFAULT_MAX_CONN);
+        args.remove(HNSW_MAX_CONNECTIONS);
+
+        this.hnswBeamWidth = ofNullable(args.get(HNSW_BEAM_WIDTH))
+                .map(value -> Integer.parseInt(value))
+                .orElse(DEFAULT_BEAM_WIDTH);
+        args.remove(HNSW_BEAM_WIDTH);
+
+        this.properties &= ~MULTIVALUED;
+        this.properties &= ~UNINVERTIBLE;
+        
+        super.init(schema, args);
+    }
+
+    public int getDimension() {
+        return dimension;
+    }
+
+    public String getCodecFormat() {
+        return codecFormat;
+    }
+
+    public Integer getHnswMaxConn() {
+        return hnswMaxConn;
+    }
+
+    public Integer getHnswBeamWidth() {
+        return hnswBeamWidth;
+    }
+
+    @Override
+    public void checkSchemaField(final SchemaField field) throws SolrException {
+        super.checkSchemaField(field);
+        if (field.multiValued()) {
+            throw new SolrException(SolrException.ErrorCode.SERVER_ERROR,
+                    getClass().getSimpleName() + " fields can not be multiValued: " + field.getName());
+        }
+
+        if (field.hasDocValues()) {
+            throw new SolrException(SolrException.ErrorCode.SERVER_ERROR,
+                    getClass().getSimpleName() + " fields can not have docValues: " + field.getName());
+        }
+    }
+    
+    public List<IndexableField> createFields(SchemaField field, Object value) {
+        List<IndexableField> fields = new ArrayList<>();
+        float[] parsedVector;
+        try {
+            parsedVector = parseVector(value);
+        } catch (RuntimeException e) {
+            throw new SolrException(SolrException.ErrorCode.SERVER_ERROR, "Error while creating field '" + field + "' from value '" + value + "', expected format:'[f1, f2, f3...fn]' e.g. [1.0, 3.4, 5.6]", e);
+        }
+

Review comment:
       if (and that is an if) the `parsedVector` typically is longer than the default initial `ArrayList` capacity and if `field.stored()` typically is true then deferring the allocation to here could avoid `fields` resizing as part of the `for` loop below e.g.
   
   ```suggestion
           List<IndexableField> fields = new ArrayList<>(parsedVector.length + 1);
   ```

##########
File path: solr/core/src/java/org/apache/solr/search/neural/KnnQParser.java
##########
@@ -0,0 +1,101 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.solr.search.neural;
+
+import org.apache.commons.lang3.StringUtils;
+import org.apache.lucene.search.Query;
+import org.apache.solr.common.SolrException;
+import org.apache.solr.common.params.SolrParams;
+import org.apache.solr.request.SolrQueryRequest;
+import org.apache.solr.schema.DenseVectorField;
+import org.apache.solr.schema.FieldType;
+import org.apache.solr.schema.SchemaField;
+import org.apache.solr.search.QParser;
+import org.apache.solr.search.QueryParsing;
+
+public class KnnQParser extends QParser {
+
+    static final String TOP_K = "topK";// retrieve the top K results based on the distance similarity function 
+    static final int DEFAULT_TOP_K = 10;
+
+    /**
+     * Constructor for the QParser
+     *
+     * @param qstr        The part of the query string specific to this parser
+     * @param localParams The set of parameters that are specific to this QParser.  See https://solr.apache.org/guide/local-parameters-in-queries.html
+     * @param params      The rest of the {@link SolrParams}
+     * @param req         The original {@link SolrQueryRequest}.
+     */
+    public KnnQParser(String qstr, SolrParams localParams, SolrParams params, SolrQueryRequest req) {
+        super(qstr, localParams, params, req);
+    }
+
+    @Override
+    public Query parse() {
+        String denseVectorField = localParams.get(QueryParsing.F);
+        String vectorToSearch = localParams.get(QueryParsing.V);
+        int topK = localParams.getInt(TOP_K, DEFAULT_TOP_K);
+
+        if (denseVectorField == null || denseVectorField.isEmpty()) {
+            throw new SolrException(SolrException.ErrorCode.BAD_REQUEST, "the Dense Vector field 'f' is missing");
+        }
+
+        if (vectorToSearch == null || vectorToSearch.isEmpty()) {
+            throw new SolrException(SolrException.ErrorCode.BAD_REQUEST, "the Dense Vector to search is missing");
+        }
+
+        SchemaField schemaField = req.getCore().getLatestSchema().getField(denseVectorField);
+        FieldType fieldType = schemaField.getType();
+        if (!(fieldType instanceof DenseVectorField)) {
+            throw new SolrException(SolrException.ErrorCode.BAD_REQUEST, "only DenseVectorField is compatible with Knn Query Parser");
+        }
+
+        DenseVectorField denseVectorType = (DenseVectorField) fieldType;
+        float[] parsedVectorToSearch = parseVector(vectorToSearch, denseVectorType.getDimension());
+        return denseVectorType.getKnnVectorQuery(schemaField, parsedVectorToSearch, topK);

Review comment:
       Wondering if altering the `getKnnVectorQuery` signature might be possible:
   
   ```
   - public Query getKnnVectorQuery(SchemaField field, float[] vectorToSearch, int topK)
   + public Query getKnnVectorQuery(String fieldName, float[] vectorToSearch, int topK)
   ```
   
   since only the field name is actually used (at present at least) and here `denseVectorType` being obtained from `schemaField` but then all of `schemaField` being passed to a `denseVectorType` method seen counter-intuitive at first glance.

##########
File path: solr/core/src/java/org/apache/solr/schema/DenseVectorField.java
##########
@@ -0,0 +1,256 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.solr.schema;
+
+import org.apache.lucene.codecs.lucene90.Lucene90HnswVectorsFormat;
+import org.apache.lucene.document.KnnVectorField;
+import org.apache.lucene.index.IndexableField;
+import org.apache.lucene.index.VectorSimilarityFunction;
+import org.apache.lucene.queries.function.ValueSource;
+import org.apache.lucene.search.KnnVectorQuery;
+import org.apache.lucene.search.Query;
+import org.apache.lucene.search.SortField;
+import org.apache.lucene.util.hnsw.HnswGraph;
+import org.apache.solr.common.SolrException;
+import org.apache.solr.search.QParser;
+import org.apache.solr.uninverting.UninvertingReader;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
+
+import static java.util.Optional.ofNullable;
+import static org.apache.lucene.codecs.lucene90.Lucene90HnswVectorsFormat.DEFAULT_BEAM_WIDTH;
+import static org.apache.lucene.codecs.lucene90.Lucene90HnswVectorsFormat.DEFAULT_MAX_CONN;
+
+/**
+ * Provides a field type to support Lucene's {@link
+ * org.apache.lucene.document.KnnVectorField}.
+ * See {@link org.apache.lucene.search.KnnVectorQuery} for more details.
+ * It supports a fixed cardinality dimension for the vector and a fixed similarity function.
+ * The default similarity is EUCLIDEAN_HNSW (L2).
+ * The default index codec format is specified in the Lucene Codec constructor.
+ * For Lucene 9.0 e.g.
+ * See {@link org.apache.lucene.codecs.lucene90.Lucene90Codec}
+ * Currently only {@link org.apache.lucene.codecs.lucene90.Lucene90HnswVectorsFormat} is supported for
+ * advanced hyper-parameter customisation.
+ * See {@link org.apache.lucene.util.hnsw.HnswGraph} for more details about the implementation. 
+ *
+ * <br>
+ * Only {@code Indexed} and {@code Stored} attributes are supported.
+ */
+public class DenseVectorField extends FloatPointField {
+
+    static final String KNN_VECTOR_DIMENSION = "vectorDimension";
+    static final String KNN_SIMILARITY_FUNCTION = "similarityFunction";
+    
+    static final String CODEC_FORMAT = "codecFormat";
+    static final String HNSW_MAX_CONNECTIONS = "hnswMaxConnections";
+    static final String HNSW_BEAM_WIDTH = "hnswBeamWidth";
+
+    int dimension;
+    VectorSimilarityFunction similarityFunction;
+    VectorSimilarityFunction DEFAULT_SIMILARITY = VectorSimilarityFunction.EUCLIDEAN;
+
+    String codecFormat;
+    /**
+     * This parameter is coupled with the {@link Lucene90HnswVectorsFormat} format implementation.
+     * Controls how many of the nearest neighbor candidates are connected to the new node. Defaults to
+     * {@link Lucene90HnswVectorsFormat#DEFAULT_MAX_CONN}. See {@link HnswGraph} for more details.
+     */
+    int hnswMaxConn;
+    /**
+     * This parameter is coupled with the {@link Lucene90HnswVectorsFormat} format implementation.
+     * The number of candidate neighbors to track while searching the graph for each newly inserted
+     * node. Defaults to to {@link Lucene90HnswVectorsFormat#DEFAULT_BEAM_WIDTH}. See {@link
+     * HnswGraph} for details.
+     */
+    int hnswBeamWidth;

Review comment:
       could these be `private` visibility since `getDimension()` etc. accessors are provided below?

##########
File path: solr/core/src/test-files/solr/collection1/conf/schema-densevector-similarity-null.xml
##########
@@ -0,0 +1,31 @@
+<?xml version="1.0" ?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements.  See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License.  You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<!-- Test schema file for DenseVectorField -->
+
+<schema name="bad-schema-densevector-similarity-null" version="1.0">

Review comment:
       possibly unintended name attribute vs. file name mismatch
   ```suggestion
   <schema name="schema-densevector-similarity-null" version="1.0">
   ```

##########
File path: solr/core/src/test/org/apache/solr/search/QueryEqualityTest.java
##########
@@ -1149,6 +1150,22 @@ public void testQueryMLT() throws Exception {
     }
   }
 
+  public void testQueryKNN() throws Exception {
+    SolrInputDocument doc = new SolrInputDocument();
+    doc.addField("id", "0");
+    doc.addField("vector", Arrays.asList(1, 2, 3, 4));
+    assertU(adoc(doc));
+    assertU(commit());
+    
+    try {
+      assertQueryEquals("knn", "{!knn f=vector}[1.0,2.0,3.0,4.0]",
+              "{!knn f=vector v=[1.0,2.0,3.0,4.0]}");
+    } finally {
+      delQ("*:*");

Review comment:
       Not sure if document adding is necessary for this test (I suspect not) but if one document is added then should test cleanup also only delete that one document?
   ```suggestion
         delQ("id:0");
   ```

##########
File path: solr/core/src/test-files/solr/collection1/conf/schema.xml
##########
@@ -50,7 +50,12 @@
   <fieldType name="pdouble" class="solr.DoublePointField" docValues="true"/>
   <fieldType name="pfloat" class="solr.FloatPointField" docValues="true"/>
   <fieldType name="pdate" class="solr.DatePointField" docValues="true"/>
-  
+
+  <!-- Dense Vector Fields -->
+  <fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine"/>
+  <fieldType name="knn_vector2" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="dot_product"/>

Review comment:
       perhaps include the dimension and/or similarity function in the type name
   ```suggestion
     <fieldType name="knn_vector_cosine" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine"/>
     <fieldType name="knn_vector_dot_product" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="dot_product"/>
   ```

##########
File path: solr/core/src/test-files/solr/collection1/conf/schema-densevector-codec-hyperparamer.xml
##########
@@ -0,0 +1,34 @@
+<?xml version="1.0" ?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements.  See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License.  You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<!-- Test schema file for DenseVectorField -->
+
+<schema name="schema-densevector" version="1.0">

Review comment:
       possibly unintended name attribute vs. file name mismatch
   ```suggestion
   <schema name="schema-densevector-codec-hyperparamer" version="1.0">
   ```

##########
File path: solr/core/src/test-files/solr/collection1/conf/bad-schema-densevector-multivalued.xml
##########
@@ -0,0 +1,31 @@
+<?xml version="1.0" ?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements.  See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License.  You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<!-- Test schema file for DenseVectorField -->
+
+<schema name="bad-schema-densevector-similarity-null" version="1.0">

Review comment:
       possibly unintended name attribute vs. file name mismatch
   ```suggestion
   <schema name="bad-schema-densevector-multivalued" version="1.0">
   ```

##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,322 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.

Review comment:
       Maybe `machine-learning.adoc` could link to `neural-search.adoc` and/or vice versa, not necessarily at this location, just generally as a way of perhaps helping users discovers more ref guide content.

##########
File path: solr/core/src/java/org/apache/solr/update/DocumentBuilder.java
##########
@@ -258,6 +246,48 @@ public static Document toDocument(SolrInputDocument doc, IndexSchema schema, boo
     return out;
   }
 
+  private static boolean addOriginalField( Object originalFieldValue, SchemaField sfield, boolean forInPlaceUpdate, Document out, Set<String> usedFields) {
+    addField(out, sfield, originalFieldValue, forInPlaceUpdate);
+    // record the field as having a value
+    usedFields.add(sfield.getName());
+    return true;
+  }
+
+  private static boolean addCopyFields(Object originalFieldValue, FieldType originalFieldType, List<CopyField> copyFields, boolean forInPlaceUpdate, String uniqueKeyFieldName, Document out, Set<String> usedFields) {

Review comment:
       minor: wrap long line(s)

##########
File path: solr/core/src/java/org/apache/solr/update/DocumentBuilder.java
##########
@@ -151,63 +153,49 @@ public static Document toDocument(SolrInputDocument doc, IndexSchema schema, boo
 
       String name = field.getName();
       SchemaField sfield = schema.getFieldOrNull(name);
-      boolean used = false;
       
+      List<CopyField> copyFields = schema.getCopyFieldsList(name);
+      if( copyFields.size() == 0 ) copyFields = null;
+
       // Make sure it has the correct number
-      if( sfield!=null && !sfield.multiValued() && field.getValueCount() > 1 ) {
+      if( sfield!=null && !(sfield.getType() instanceof DenseVectorField) && !sfield.multiValued() && field.getValueCount() > 1 ) {

Review comment:
       subjective: add new specialised clauses at the end with short-circuit evaluation in mind
   ```suggestion
         if( sfield!=null && !sfield.multiValued() && field.getValueCount() > 1 && !(sfield.getType() instanceof DenseVectorField) ) {
   ```

##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,322 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not be solved simply by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+
+=== DenseVectorField
+The Dense Vector field gives the possibility of indexing and searching dense vectors of float elements.
+
+e.g.
+
+`[1.0, 2.5, 3.7, 4.1]` (array of float elements)
+
+Here's how `DenseVectorField` should be configured in the schema:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`vectorDimension`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The dimension of the dense vector to pass in.
++
+Accepted values:
+Integer < = 1024.
+
+`similarityFunction`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `euclidean`
+|===
++
+Vector similarity function; used in search to return top K most similar vectors to a target vector.
++
+Accepted values: `euclidean`, `dot_product`  or `cosine`.
+
+* `euclidean`: https://en.wikipedia.org/wiki/Euclidean_distance[Euclidean distance]
+* `dot_product`: https://en.wikipedia.org/wiki/Dot_product[Dot product]. *NOTE*: this similarity is intended as an optimized way to perform cosine similarity. In order to use it, all vectors must be of unit length, including both document and query vectors. Using dot product with vectors that are not unit length can result in errors or poor search results..
+* `cosine`: https://en.wikipedia.org/wiki/Cosine_similarity[Cosine similarity]. *NOTE*: the preferred way to perform cosine similarity is to normalize all vectors to unit length, and instead use DOT_PRODUCT. You should only use this function if you need to preserve the original vectors and cannot normalize them in advance.
+
+*N.B.* To use the following advanced parameters that customise the codec format
+and the hyper-parameter of the HNSW algorithm make sure you set this configuration in the solrconfig.xml:
+[source,xml]
+<config>
+<codecFactory class="solr.SchemaCodecFactory"/>
+...
+
+Here's how `DenseVectorField` can be configured with the advanced codec hyper-parameters:
+
+[source,xml]
+<fieldType name="knn_vector" class="solr.DenseVectorField" vectorDimension="4" similarityFunction="cosine" codecFormat="Lucene90HnswVectorsFormat" hnswMaxConnections="10" hnswBeamWidth="40"/>
+<field name="vector" type="knn_vector" indexed="true" stored="true"/>
+
+`codecFormat`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: `Lucene90HnswVectorsFormat`
+|===
++
+(advanced) Specifies the knn codec implementation to use
++
+
+Accepted values: `Lucene90HnswVectorsFormat`.
+
+Please note that the `codecFormat` accepted values may change in future releases.
+
+
+
+[NOTE]
+Lucene index back-compatibility is only supported for the default codec.
+If you choose to customize the `codecFormat` in your schema, upgrading to a future version of Solr may require you to either switch back to the default codec and optimize your index to rewrite it into the default codec before upgrading, or re-build your entire index from scratch after upgrading.
+
+`hnswMaxConnections`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 16
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+Controls how many of the nearest neighbor candidates are connected to the new node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `M` from the later paper.
++
+Accepted values:
+Integer.
+
+`hnswBeamWidth`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 100
+|===
++
+(advanced) This parameter is specific for the `Lucene90HnswVectorsFormat` codec format:
++
+It is the number of nearest neighbor candidates to track while searching the graph for each newly inserted node.
++
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
++
+It has the same meaning as `efConstruction` from the later paper.
++
+Accepted values:
+Integer.
+
+DenseVectorField supports the attributes: `indexed`, `stored`.
+
+*N.B.* currently multivalue is not supported
+
+Here's how a `DenseVectorField` should be indexed:
+
+[.dynamic-tabs]
+--
+[example.tab-pane#json]
+====
+[.tab-label]*JSON*
+[source,json]
+----
+[{ "id": "1",
+"vector": [1.0, 2.5, 3.7, 4.1]
+},
+{ "id": "2",
+"vector": [1.5, 5.5, 6.7, 65.1]
+}
+]
+----
+====
+
+[example.tab-pane#xml]
+====
+[.tab-label]*XML*
+[source,xml]
+----
+<add>
+<doc>
+<field name="id">1</field>
+<field name="vector">1.0</field>
+<field name="vector">2.5</field>
+<field name="vector">3.7</field>
+<field name="vector">4.1</field>
+</doc>
+<doc>
+<field name="id">2</field>
+<field name="vector">1.5</field>
+<field name="vector">5.5</field>
+<field name="vector">6.7</field>
+<field name="vector">65.1</field>
+</doc>
+</add>
+----
+====
+
+[example.tab-pane#solrj]
+====
+[.tab-label]*SolrJ*
+[source,java,indent=0]
+----
+final SolrClient client = getSolrClient();
+
+final SolrInputDocument d1 = new SolrInputDocument();
+d1.setField("id", "1");
+d1.setField("vector", Arrays.asList(1.0f, 2.5f, 3.7f, 4.1f));
+
+
+final SolrInputDocument d2 = new SolrInputDocument();
+d2.setField("id", "2");
+d2.setField("vector", Arrays.asList(1.5f, 5.5f, 6.7f, 65.1f));
+
+client.add(Arrays.asList(d1, d2));
+----
+====
+--
+
+== Query Time
+This is the list of Apache Solr query approaches designed to support Neural Search:
+
+=== knn Query Parser
+The `knn` K-Nearest Neighbors query parser allows to find the k-nearest documents to the target vector according to indexed dense vectors in the given field.
+
+It takes the following parameters:
+
+`f`::
++
+[%autowidth,frame=none]
+|===
+|Mandatory
+|===
++
+The DenseVectorField to search in.
+
+`topK`::
++
+[%autowidth,frame=none]
+|===
+|Optional |Default: 10
+|===
++
+How many k-nearest results to return.
+
+Here's how to run a KNN search:
+
+[source,text]
+&q={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]
+
+The search results retrieved are the K-nearest to the vector in input `[1.0, 2.0, 3.0, 4.0]`, ranked by the similarityFunction configured at indexing time.
+
+==== Usage with Filter Queries
+The `knn` query parser can be used in filter queries:
+[source,text]
+&q=id:(1 2 3)&fq={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]
+
+The `knn` query parser can be used with filter queries:
+[source,text]
+&q={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]&fq=id:(1 2 3)
+
+[IMPORTANT]
+====
+When using `knn` in these scenarios make sure you have a clear understanding of how filter queries work in Apache Solr:
+
+The Ranked List of document IDs resulting from the main query `q` is intersected with the set of document IDs deriving from each filter query `fq`.
+
+e.g.
+
+Ranked List from `q`=`[ID1, ID4, ID2, ID10]` <intersects> Set from `fq`=`{ID3, ID2, ID9, ID4}` = `[ID4,ID2]`
+====
+
+
+==== Usage as Re-Ranking Query
+The `knn` query parser can be used to rerank first pass query results:
+[source,text]
+&q=id:(3 4 9 2)&rq={!rerank reRankQuery=$rqq reRankDocs=4 reRankWeight=1}&rqq={!knn f=vector topK=10}[1.0, 2.0, 3.0, 4.0]
+
+[IMPORTANT]
+====
+When using `knn` in reranking pay attention to the `topK` parameter.
+
+The second pass score(deriving from knn) is calculated only if the document `d` from the first pass is within
+the K-nearest neighbors(*in the whole index*) of the target vector to search.
+
+This means the second pass `knn` is executed on the whole index anyway, which is a current limitation.
+
+The final ranked list of results will have the first pass score(main query `q`) added to the second pass score(the approximated similarityFunction distance to the target vector to search) multiplied by a multiplicative factor(reRankWeight).
+
+Details about using the ReRank Query Parser can be found in the <<query-re-ranking.adoc#,Query Re-Ranking>> section.

Review comment:
       `query-re-ranking.adoc` could list `knn` also and link to `neural-search.adoc` here.

##########
File path: solr/core/src/java/org/apache/solr/schema/DenseVectorField.java
##########
@@ -0,0 +1,256 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.solr.schema;
+
+import org.apache.lucene.codecs.lucene90.Lucene90HnswVectorsFormat;
+import org.apache.lucene.document.KnnVectorField;
+import org.apache.lucene.index.IndexableField;
+import org.apache.lucene.index.VectorSimilarityFunction;
+import org.apache.lucene.queries.function.ValueSource;
+import org.apache.lucene.search.KnnVectorQuery;
+import org.apache.lucene.search.Query;
+import org.apache.lucene.search.SortField;
+import org.apache.lucene.util.hnsw.HnswGraph;
+import org.apache.solr.common.SolrException;
+import org.apache.solr.search.QParser;
+import org.apache.solr.uninverting.UninvertingReader;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
+
+import static java.util.Optional.ofNullable;
+import static org.apache.lucene.codecs.lucene90.Lucene90HnswVectorsFormat.DEFAULT_BEAM_WIDTH;
+import static org.apache.lucene.codecs.lucene90.Lucene90HnswVectorsFormat.DEFAULT_MAX_CONN;
+
+/**
+ * Provides a field type to support Lucene's {@link
+ * org.apache.lucene.document.KnnVectorField}.
+ * See {@link org.apache.lucene.search.KnnVectorQuery} for more details.
+ * It supports a fixed cardinality dimension for the vector and a fixed similarity function.
+ * The default similarity is EUCLIDEAN_HNSW (L2).
+ * The default index codec format is specified in the Lucene Codec constructor.
+ * For Lucene 9.0 e.g.
+ * See {@link org.apache.lucene.codecs.lucene90.Lucene90Codec}
+ * Currently only {@link org.apache.lucene.codecs.lucene90.Lucene90HnswVectorsFormat} is supported for
+ * advanced hyper-parameter customisation.
+ * See {@link org.apache.lucene.util.hnsw.HnswGraph} for more details about the implementation. 
+ *
+ * <br>
+ * Only {@code Indexed} and {@code Stored} attributes are supported.
+ */
+public class DenseVectorField extends FloatPointField {
+
+    static final String KNN_VECTOR_DIMENSION = "vectorDimension";
+    static final String KNN_SIMILARITY_FUNCTION = "similarityFunction";
+    
+    static final String CODEC_FORMAT = "codecFormat";
+    static final String HNSW_MAX_CONNECTIONS = "hnswMaxConnections";
+    static final String HNSW_BEAM_WIDTH = "hnswBeamWidth";
+
+    int dimension;
+    VectorSimilarityFunction similarityFunction;
+    VectorSimilarityFunction DEFAULT_SIMILARITY = VectorSimilarityFunction.EUCLIDEAN;
+
+    String codecFormat;
+    /**
+     * This parameter is coupled with the {@link Lucene90HnswVectorsFormat} format implementation.
+     * Controls how many of the nearest neighbor candidates are connected to the new node. Defaults to
+     * {@link Lucene90HnswVectorsFormat#DEFAULT_MAX_CONN}. See {@link HnswGraph} for more details.
+     */
+    int hnswMaxConn;
+    /**
+     * This parameter is coupled with the {@link Lucene90HnswVectorsFormat} format implementation.
+     * The number of candidate neighbors to track while searching the graph for each newly inserted
+     * node. Defaults to to {@link Lucene90HnswVectorsFormat#DEFAULT_BEAM_WIDTH}. See {@link
+     * HnswGraph} for details.
+     */
+    int hnswBeamWidth;
+
+    @Override
+    public void init(IndexSchema schema, Map<String, String> args) {
+        this.dimension = ofNullable(args.get(KNN_VECTOR_DIMENSION))
+                .map(value -> Integer.parseInt(value))
+                .orElseThrow(() -> new SolrException(SolrException.ErrorCode.SERVER_ERROR, "the vector dimension is a mandatory parameter"));
+        args.remove(KNN_VECTOR_DIMENSION);
+
+        this.similarityFunction = ofNullable(args.get(KNN_SIMILARITY_FUNCTION))
+                .map(value -> VectorSimilarityFunction.valueOf(value.toUpperCase(Locale.ROOT)))
+                .orElse(DEFAULT_SIMILARITY);
+        args.remove(KNN_SIMILARITY_FUNCTION);
+
+        this.codecFormat = args.get(CODEC_FORMAT);
+        args.remove(CODEC_FORMAT);
+
+        this.hnswMaxConn = ofNullable(args.get(HNSW_MAX_CONNECTIONS))
+                .map(value -> Integer.parseInt(value))
+                .orElse(DEFAULT_MAX_CONN);
+        args.remove(HNSW_MAX_CONNECTIONS);
+
+        this.hnswBeamWidth = ofNullable(args.get(HNSW_BEAM_WIDTH))
+                .map(value -> Integer.parseInt(value))
+                .orElse(DEFAULT_BEAM_WIDTH);
+        args.remove(HNSW_BEAM_WIDTH);
+
+        this.properties &= ~MULTIVALUED;
+        this.properties &= ~UNINVERTIBLE;
+        
+        super.init(schema, args);
+    }
+
+    public int getDimension() {
+        return dimension;
+    }
+
+    public String getCodecFormat() {
+        return codecFormat;
+    }
+
+    public Integer getHnswMaxConn() {
+        return hnswMaxConn;
+    }
+
+    public Integer getHnswBeamWidth() {
+        return hnswBeamWidth;
+    }
+
+    @Override
+    public void checkSchemaField(final SchemaField field) throws SolrException {
+        super.checkSchemaField(field);
+        if (field.multiValued()) {
+            throw new SolrException(SolrException.ErrorCode.SERVER_ERROR,
+                    getClass().getSimpleName() + " fields can not be multiValued: " + field.getName());
+        }
+
+        if (field.hasDocValues()) {
+            throw new SolrException(SolrException.ErrorCode.SERVER_ERROR,
+                    getClass().getSimpleName() + " fields can not have docValues: " + field.getName());
+        }
+    }
+    
+    public List<IndexableField> createFields(SchemaField field, Object value) {
+        List<IndexableField> fields = new ArrayList<>();
+        float[] parsedVector;
+        try {
+            parsedVector = parseVector(value);
+        } catch (RuntimeException e) {
+            throw new SolrException(SolrException.ErrorCode.SERVER_ERROR, "Error while creating field '" + field + "' from value '" + value + "', expected format:'[f1, f2, f3...fn]' e.g. [1.0, 3.4, 5.6]", e);
+        }
+
+        if (field.indexed()) {
+            fields.add(createField(field, parsedVector));
+        }
+        if (field.stored()) {
+            for (float vectorElement : parsedVector) {
+                fields.add(getStoredField(field, vectorElement));
+            }
+        }
+        return fields;
+    }
+
+    @Override
+    public IndexableField createField(SchemaField field, Object parsedVector) {
+        float[] typedVector;
+        if (parsedVector == null) return null;
+        typedVector = (float[]) parsedVector;
+        return new KnnVectorField(field.getName(), typedVector, similarityFunction);
+    }
+
+    /**
+     * Index Time Parsing
+     * The inputValue is an ArrayList with a type that dipends on the loader used:
+     * - {@link org.apache.solr.handler.loader.XMLLoader}, {@link org.apache.solr.handler.loader.CSVLoader} produces an ArrayList of String
+     * - {@link org.apache.solr.handler.loader.JsonLoader} produces an ArrayList of Double
+     * - {@link org.apache.solr.handler.loader.JavabinLoader} produces an ArrayList of Float
+     *
+     * @param inputValue - An {@link ArrayList} containing the elements of the vector
+     * @return the vector parsed
+     */
+    float[] parseVector(Object inputValue) {
+        if (!(inputValue instanceof List)) {
+            throw new SolrException(SolrException.ErrorCode.BAD_REQUEST, "incorrect vector format." +
+                    " The expected format is an array :'[f1,f2..f3]' where each element f is a float");
+        }
+        List<?> inputVector = (List<?>) inputValue;
+        if (inputVector.size() != dimension) {
+            throw new SolrException(SolrException.ErrorCode.BAD_REQUEST, "incorrect vector dimension." +
+                    " The vector value has size "
+                    + inputVector.size() + " while it is expected a vector with size " + dimension);
+        }
+
+        float[] vector = new float[dimension];
+        if (inputVector.get(0) instanceof CharSequence) {
+            for (int i = 0; i < dimension; i++) {
+                try {
+                    vector[i] = Float.parseFloat(inputVector.get(i).toString());
+                } catch (NumberFormatException e) {
+                    throw new SolrException(SolrException.ErrorCode.BAD_REQUEST, "incorrect vector element: '" + inputVector.get(i) +
+                            "'. The expected format is:'[f1,f2..f3]' where each element f is a float");
+                }
+            }
+        } else if (inputVector.get(0) instanceof Number) {
+            for (int i = 0; i < dimension; i++) {
+                vector[i] = ((Number) inputVector.get(i)).floatValue();
+            }
+        }
+
+        return vector;
+    }
+
+    @Override
+    public UninvertingReader.Type getUninversionType(SchemaField sf) {
+        return null;
+    }
+
+    @Override
+    public ValueSource getValueSource(SchemaField field, QParser parser) {
+        throw new SolrException(SolrException.ErrorCode.BAD_REQUEST,
+                "Function queries are not supported for Dense Vector fields.");
+    }
+
+    public Query getKnnVectorQuery(SchemaField field, float[] vectorToSearch, int topK) {
+        return new KnnVectorQuery(field.getName(), vectorToSearch, topK);
+    }
+
+    /**
+     * Not Supported

Review comment:
       It's nice to have the `Please use the {!knn} query parser ...` signpost in the exception that is thrown. Perhaps the javadocs here could also reference or link it.

##########
File path: solr/core/src/java/org/apache/solr/update/DocumentBuilder.java
##########
@@ -151,63 +153,49 @@ public static Document toDocument(SolrInputDocument doc, IndexSchema schema, boo
 
       String name = field.getName();
       SchemaField sfield = schema.getFieldOrNull(name);
-      boolean used = false;
       
+      List<CopyField> copyFields = schema.getCopyFieldsList(name);
+      if( copyFields.size() == 0 ) copyFields = null;
+
       // Make sure it has the correct number
-      if( sfield!=null && !sfield.multiValued() && field.getValueCount() > 1 ) {
+      if( sfield!=null && !(sfield.getType() instanceof DenseVectorField) && !sfield.multiValued() && field.getValueCount() > 1 ) {
         throw new SolrException( SolrException.ErrorCode.BAD_REQUEST,
-            "ERROR: "+getID(doc, schema)+"multiple values encountered for non multiValued field " + 
-              sfield.getName() + ": " +field.getValue() );
+                "ERROR: "+getID(doc, schema)+"multiple values encountered for non multiValued field " +
+                        sfield.getName() + ": " +field.getValue() );
       }
 
-      List<CopyField> copyFields = schema.getCopyFieldsList(name);
-      if( copyFields.size() == 0 ) copyFields = null;
-

Review comment:
       could `copyFields` remain here? it moved 'up' but at a glance appears to not be needed any earlier?




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r786748882



##########
File path: solr/core/src/java/org/apache/solr/schema/DenseVectorField.java
##########
@@ -0,0 +1,256 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.solr.schema;
+
+import org.apache.lucene.codecs.lucene90.Lucene90HnswVectorsFormat;
+import org.apache.lucene.document.KnnVectorField;
+import org.apache.lucene.index.IndexableField;
+import org.apache.lucene.index.VectorSimilarityFunction;
+import org.apache.lucene.queries.function.ValueSource;
+import org.apache.lucene.search.KnnVectorQuery;
+import org.apache.lucene.search.Query;
+import org.apache.lucene.search.SortField;
+import org.apache.lucene.util.hnsw.HnswGraph;
+import org.apache.solr.common.SolrException;
+import org.apache.solr.search.QParser;
+import org.apache.solr.uninverting.UninvertingReader;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
+
+import static java.util.Optional.ofNullable;
+import static org.apache.lucene.codecs.lucene90.Lucene90HnswVectorsFormat.DEFAULT_BEAM_WIDTH;
+import static org.apache.lucene.codecs.lucene90.Lucene90HnswVectorsFormat.DEFAULT_MAX_CONN;
+
+/**
+ * Provides a field type to support Lucene's {@link
+ * org.apache.lucene.document.KnnVectorField}.
+ * See {@link org.apache.lucene.search.KnnVectorQuery} for more details.
+ * It supports a fixed cardinality dimension for the vector and a fixed similarity function.
+ * The default similarity is EUCLIDEAN_HNSW (L2).
+ * The default index codec format is specified in the Lucene Codec constructor.
+ * For Lucene 9.0 e.g.
+ * See {@link org.apache.lucene.codecs.lucene90.Lucene90Codec}
+ * Currently only {@link org.apache.lucene.codecs.lucene90.Lucene90HnswVectorsFormat} is supported for
+ * advanced hyper-parameter customisation.
+ * See {@link org.apache.lucene.util.hnsw.HnswGraph} for more details about the implementation. 
+ *
+ * <br>
+ * Only {@code Indexed} and {@code Stored} attributes are supported.
+ */
+public class DenseVectorField extends FloatPointField {
+
+    static final String KNN_VECTOR_DIMENSION = "vectorDimension";
+    static final String KNN_SIMILARITY_FUNCTION = "similarityFunction";
+    
+    static final String CODEC_FORMAT = "codecFormat";
+    static final String HNSW_MAX_CONNECTIONS = "hnswMaxConnections";
+    static final String HNSW_BEAM_WIDTH = "hnswBeamWidth";
+
+    int dimension;
+    VectorSimilarityFunction similarityFunction;
+    VectorSimilarityFunction DEFAULT_SIMILARITY = VectorSimilarityFunction.EUCLIDEAN;
+
+    String codecFormat;
+    /**
+     * This parameter is coupled with the {@link Lucene90HnswVectorsFormat} format implementation.
+     * Controls how many of the nearest neighbor candidates are connected to the new node. Defaults to
+     * {@link Lucene90HnswVectorsFormat#DEFAULT_MAX_CONN}. See {@link HnswGraph} for more details.
+     */
+    int hnswMaxConn;
+    /**
+     * This parameter is coupled with the {@link Lucene90HnswVectorsFormat} format implementation.
+     * The number of candidate neighbors to track while searching the graph for each newly inserted
+     * node. Defaults to to {@link Lucene90HnswVectorsFormat#DEFAULT_BEAM_WIDTH}. See {@link
+     * HnswGraph} for details.
+     */
+    int hnswBeamWidth;
+
+    @Override
+    public void init(IndexSchema schema, Map<String, String> args) {
+        this.dimension = ofNullable(args.get(KNN_VECTOR_DIMENSION))
+                .map(value -> Integer.parseInt(value))
+                .orElseThrow(() -> new SolrException(SolrException.ErrorCode.SERVER_ERROR, "the vector dimension is a mandatory parameter"));
+        args.remove(KNN_VECTOR_DIMENSION);
+
+        this.similarityFunction = ofNullable(args.get(KNN_SIMILARITY_FUNCTION))
+                .map(value -> VectorSimilarityFunction.valueOf(value.toUpperCase(Locale.ROOT)))
+                .orElse(DEFAULT_SIMILARITY);
+        args.remove(KNN_SIMILARITY_FUNCTION);
+
+        this.codecFormat = args.get(CODEC_FORMAT);
+        args.remove(CODEC_FORMAT);
+
+        this.hnswMaxConn = ofNullable(args.get(HNSW_MAX_CONNECTIONS))
+                .map(value -> Integer.parseInt(value))
+                .orElse(DEFAULT_MAX_CONN);
+        args.remove(HNSW_MAX_CONNECTIONS);
+
+        this.hnswBeamWidth = ofNullable(args.get(HNSW_BEAM_WIDTH))
+                .map(value -> Integer.parseInt(value))
+                .orElse(DEFAULT_BEAM_WIDTH);
+        args.remove(HNSW_BEAM_WIDTH);
+
+        this.properties &= ~MULTIVALUED;
+        this.properties &= ~UNINVERTIBLE;
+        
+        super.init(schema, args);
+    }
+
+    public int getDimension() {
+        return dimension;
+    }
+
+    public String getCodecFormat() {
+        return codecFormat;
+    }
+
+    public Integer getHnswMaxConn() {
+        return hnswMaxConn;
+    }
+
+    public Integer getHnswBeamWidth() {
+        return hnswBeamWidth;
+    }
+
+    @Override
+    public void checkSchemaField(final SchemaField field) throws SolrException {
+        super.checkSchemaField(field);
+        if (field.multiValued()) {
+            throw new SolrException(SolrException.ErrorCode.SERVER_ERROR,
+                    getClass().getSimpleName() + " fields can not be multiValued: " + field.getName());
+        }
+
+        if (field.hasDocValues()) {
+            throw new SolrException(SolrException.ErrorCode.SERVER_ERROR,
+                    getClass().getSimpleName() + " fields can not have docValues: " + field.getName());
+        }
+    }
+    
+    public List<IndexableField> createFields(SchemaField field, Object value) {
+        List<IndexableField> fields = new ArrayList<>();
+        float[] parsedVector;
+        try {
+            parsedVector = parseVector(value);
+        } catch (RuntimeException e) {
+            throw new SolrException(SolrException.ErrorCode.SERVER_ERROR, "Error while creating field '" + field + "' from value '" + value + "', expected format:'[f1, f2, f3...fn]' e.g. [1.0, 3.4, 5.6]", e);
+        }
+
+        if (field.indexed()) {
+            fields.add(createField(field, parsedVector));
+        }
+        if (field.stored()) {
+            for (float vectorElement : parsedVector) {
+                fields.add(getStoredField(field, vectorElement));
+            }
+        }
+        return fields;
+    }
+
+    @Override
+    public IndexableField createField(SchemaField field, Object parsedVector) {
+        float[] typedVector;
+        if (parsedVector == null) return null;
+        typedVector = (float[]) parsedVector;
+        return new KnnVectorField(field.getName(), typedVector, similarityFunction);
+    }
+
+    /**
+     * Index Time Parsing
+     * The inputValue is an ArrayList with a type that dipends on the loader used:
+     * - {@link org.apache.solr.handler.loader.XMLLoader}, {@link org.apache.solr.handler.loader.CSVLoader} produces an ArrayList of String
+     * - {@link org.apache.solr.handler.loader.JsonLoader} produces an ArrayList of Double
+     * - {@link org.apache.solr.handler.loader.JavabinLoader} produces an ArrayList of Float
+     *
+     * @param inputValue - An {@link ArrayList} containing the elements of the vector
+     * @return the vector parsed
+     */
+    float[] parseVector(Object inputValue) {
+        if (!(inputValue instanceof List)) {
+            throw new SolrException(SolrException.ErrorCode.BAD_REQUEST, "incorrect vector format." +
+                    " The expected format is an array :'[f1,f2..f3]' where each element f is a float");
+        }
+        List<?> inputVector = (List<?>) inputValue;
+        if (inputVector.size() != dimension) {
+            throw new SolrException(SolrException.ErrorCode.BAD_REQUEST, "incorrect vector dimension." +
+                    " The vector value has size "
+                    + inputVector.size() + " while it is expected a vector with size " + dimension);
+        }
+
+        float[] vector = new float[dimension];
+        if (inputVector.get(0) instanceof CharSequence) {
+            for (int i = 0; i < dimension; i++) {
+                try {
+                    vector[i] = Float.parseFloat(inputVector.get(i).toString());
+                } catch (NumberFormatException e) {
+                    throw new SolrException(SolrException.ErrorCode.BAD_REQUEST, "incorrect vector element: '" + inputVector.get(i) +
+                            "'. The expected format is:'[f1,f2..f3]' where each element f is a float");
+                }
+            }
+        } else if (inputVector.get(0) instanceof Number) {
+            for (int i = 0; i < dimension; i++) {
+                vector[i] = ((Number) inputVector.get(i)).floatValue();
+            }
+        }

Review comment:
       Done!




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] joel-bernstein commented on a change in pull request #476: SOLR-15880

Posted by GitBox <gi...@apache.org>.
joel-bernstein commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r786285685



##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,322 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.

Review comment:
       I'll add a link and a section to machine-learning.adoc showing how to integrate with math expressions. This is is now the key machine learning feature in Solr and its fits quite nicely with Streaming Expressions and math expressions. I'll add the docs after the patch lands.




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880: K Nearest Neighbors Search

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r787636712



##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+
+In particular the advent of https://en.wikipedia.org/wiki/Deep_learning[Deep Learning] introduced the use of deep neural networks to solve complex problems that could not be solved simply by an algorithm.
+
+Deep Learning can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+=== Dense Vector Representation 
+A Dense vector describes information as an array of elements, each of them explicitly defined.
+
+Various Deep Learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] are able to encode textual information as dense vectors, to be used for Dense Retrieval strategies.
+
+For additional information you can refer to this https://sease.io/2021/12/using-bert-to-improve-search-relevance.html[blog post].
+
+=== Dense Retrieval
+Given a dense vector `v` that models the information need, the easiest approach for providing dense vector retrieval would be to calculate the distance(euclidean, dot product, etc.) between `v` and each vector `d` that represents a document in the corpus of information.
+
+This approach is quite expensive, so many approximate strategies are currently under active research.
+
+The strategy implemented in Apache Lucene and used by Apache Solr is based on Navigable Small-world graph.
+
+It provides efficient approximate nearest neighbor search for high dimensional vectors.
+
+See https://doi.org/10.1016/j.is.2013.10.006[Approximate nearest neighbor algorithm based on navigable small world graphs [2014]] and https://arxiv.org/abs/1603.09320[this paper [2018]] for details.
+
+
+== Index Time
+This is the list of Apache Solr field types designed to support Neural Search:
+
+=== DenseVectorField
+The Dense Vector field gives the possibility of indexing and searching dense vectors of float elements.
+
+e.g.
+

Review comment:
       Makes sense!




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] magibney commented on a change in pull request #476: SOLR-15880: K Nearest Neighbors Search

Posted by GitBox <gi...@apache.org>.
magibney commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r787980804



##########
File path: solr/solr-ref-guide/src/dense-vector-search.adoc
##########
@@ -0,0 +1,308 @@
+= Dense Vector Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+The Apache Solr *Dense Vector Search* module adds support for indexing and searching dense numerical vectors.
+
+https://en.wikipedia.org/wiki/Deep_learning[Deep learning] can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+These neural network-based techniques are usually referred to as neural search, an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Important Concepts
+
+=== Dense Vector Representation 
+A dense vector describes information as an array of elements, each of them explicitly defined.

Review comment:
       >each of them explicitly defined
   
   This statement reads a little bit unclear to me. In my reading, this means that the _values_ of vectors are not implicitly derived from "normal" doc or user text input (in the manner of tokenization), but are rather determined externally (e.g., by a custom model) and supplied explicitly to Solr. But it's easy to interpret this statement as suggesting that the semantic significance of each dimension is explicitly defined, which iiuc is definitely _not_ the case.
   
   If I'm correctly characterizing the meaning of the above statement (and please correct me if I'm not!), I think it might be worth expanding on this a bit to explicitly clarify that in order to leverage this feature, a user _needs_ an external means of generating vectors from content. I think in context, that's probably what you're getting at by referring to "Various deep learning models..." immediately below, but I think the connection could stand to be more explicit. (incidentally, even if perhaps not worth noting in the refguide: there may well be applications -- e.g., scientific? -- for searching vector similarity that actually have nothing at all to do with language models, machine learning, etc...)




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] magibney commented on a change in pull request #476: SOLR-15880: K Nearest Neighbors Search

Posted by GitBox <gi...@apache.org>.
magibney commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r788954745



##########
File path: solr/solr-ref-guide/src/dense-vector-search.adoc
##########
@@ -0,0 +1,308 @@
+= Dense Vector Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+The Apache Solr *Dense Vector Search* module adds support for indexing and searching dense numerical vectors.
+
+https://en.wikipedia.org/wiki/Deep_learning[Deep learning] can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+These neural network-based techniques are usually referred to as neural search, an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Important Concepts
+
+=== Dense Vector Representation 
+A dense vector describes information as an array of elements, each of them explicitly defined.

Review comment:
       Ahh I see! Sorry for the delayed response. I'll take a crack at this, feel free to take or leave this suggestion:
   
   ```
   === Dense Vector Representation 
   A traditional "tokenized inverted index" can be considered to model text as a "sparse" vector, in which each term in the index corresponds to one vector dimension. In such a model, the number of dimensions is generally quite high (corresponding to term cardinality), and the vector for any given document contains mostly "zeros" (hence it is "sparse", as only a handful of terms that exist in the overall index will be present in any given document).
   
   "Dense vector" representation contrasts with term-based "sparse vector" representation in that it distills semantic meaning into a fixed (and limited) number of dimensions. The number of dimensions in this approach is generally much lower than the "sparse" case, and the vector for any given document is "dense", as most of its dimensions are populated by non-zero values.
   
   Solr exposes the capability to index and search dense vectors; but in contrast to the "sparse" approach (for which Solr provides tokenizers to "generate sparse vectors" directly from text input) the task of _generating_ vectors must be handled in application logic external to Solr. There may be cases where it makes sense to directly search data that natively exists as a vector (e.g., scientific data); but in a "text search" context, it is likely that users will leverage deep learning models such as https://en.wikipedia.org/wiki/BERT_(language_model)[BERT] to encode textual information as dense vectors, supplying the resulting vectors to Solr explicitly at index and query time.
   ```
   




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on pull request #476: SOLR-15880: K Nearest Neighbors Search

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on pull request #476:
URL: https://github.com/apache/solr/pull/476#issuecomment-1016416766


   I should have addressed most of the comments regarding the documentation.
   Thank you very much for the suggestions @ctargett , they are really valuable, especially for a software engineer that rarely has touched the solr doc like me :) 
   
   Only a few questions remain, that I don't think are really critical, so I'll wait for some reply on them before committing.
   
   In regards to the "Neural Search" name, as I expressed in a comment before, I think it's fine, but I'll raise the matter to the wider community through slack for a quick feedback!
   
   Cheers and thanks again!
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880: K Nearest Neighbors Search

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r789563790



##########
File path: solr/solr-ref-guide/src/dense-vector-search.adoc
##########
@@ -0,0 +1,308 @@
+= Dense Vector Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+The Apache Solr *Dense Vector Search* module adds support for indexing and searching dense numerical vectors.
+
+https://en.wikipedia.org/wiki/Deep_learning[Deep learning] can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+These neural network-based techniques are usually referred to as neural search, an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Important Concepts
+
+=== Dense Vector Representation 
+A dense vector describes information as an array of elements, each of them explicitly defined.

Review comment:
       Thanks again @magibney for the feedback, I gave it a go!
   I incorporated your suggestions (with some minor changes here and there), hopefully, it looks all right now!




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880: K Nearest Neighbors Search

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r787629854



##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+
+=== Deep Learning
+
+More and more frequently, we hear about how Artificial Intelligence (AI) permeates every aspect of our lives.
+
+When we talk about AI we are referring to a superset of techniques that enable machines to learn and show intelligence like humans.
+
+Since computing power has strongly and steadily advanced in the recent past, AI has seen a resurgence lately and it is now used in many domains, including software engineering and Information Retrieval (the science that regulates Search Engines and similar systems).
+

Review comment:
       Removed! Thanks!




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880: K Nearest Neighbors Search

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r787680347



##########
File path: solr/solr-ref-guide/src/neural-search.adoc
##########
@@ -0,0 +1,324 @@
+= Neural Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+Search comprises of performing four primary steps:
+
+* generate a representation of the query that specifies the information need
+* generate a representation of the document that captures the information contained
+* match the query and the document representations from the corpus of information
+* assign a score to each matched document in order to establish a meaningful document ranking by relevance in the results
+
+The Apache Solr *Neural Search* module adds support for neural networks based techniques that can improve various aspects of search.
+
+These techniques can be differentiated based on whether they affect the query representation, the document representation, or the estimation of the relevance score.
+
+Neural Search is an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Neural Search Concepts
+

Review comment:
       The intention of the Neural Search concepts area is to give a nice and quick introduction to the user, including useful references.
   If I rename it to "Important Concepts", any better?
   Let me know, I would like to merge this contribution soon, if you have any additional text suggestions I can add them!
   




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org


[GitHub] [solr] alessandrobenedetti commented on a change in pull request #476: SOLR-15880: K Nearest Neighbors Search

Posted by GitBox <gi...@apache.org>.
alessandrobenedetti commented on a change in pull request #476:
URL: https://github.com/apache/solr/pull/476#discussion_r789862393



##########
File path: solr/solr-ref-guide/src/dense-vector-search.adoc
##########
@@ -0,0 +1,308 @@
+= Dense Vector Search
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+The Apache Solr *Dense Vector Search* module adds support for indexing and searching dense numerical vectors.
+
+https://en.wikipedia.org/wiki/Deep_learning[Deep learning] can be used to produce a vector representation of both the query and the documents in a corpus of information.
+
+These neural network-based techniques are usually referred to as neural search, an industry derivation from the academic field of https://www.microsoft.com/en-us/research/uploads/prod/2017/06/fntir2018-neuralir-mitra.pdf[Neural information Retrieval].
+
+== Important Concepts
+
+=== Dense Vector Representation 
+A dense vector describes information as an array of elements, each of them explicitly defined.

Review comment:
       I agree with your observations!
   From a practical perspective, how do you want me to change the current documentation piece in your opinion?




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org