From 7a86e6f1f8ae022a380baa12016d40d7f81a511b Mon Sep 17 00:00:00 2001 From: Sarah Welton Date: Mon, 18 Nov 2024 15:25:16 -0500 Subject: [PATCH 1/2] [DOC-12253] Add vector search response examples --- .../create-vector-search-index-response.json | 5 + .../examples/run-vector-search-payload.sh | 2 +- .../examples/run-vector-search-response.json | 125 ++++++++++++++++++ .../create-vector-search-index-rest-api.adoc | 10 ++ .../pages/run-vector-search-rest-api.adoc | 7 + 5 files changed, 148 insertions(+), 1 deletion(-) create mode 100644 modules/vector-search/examples/create-vector-search-index-response.json create mode 100644 modules/vector-search/examples/run-vector-search-response.json diff --git a/modules/vector-search/examples/create-vector-search-index-response.json b/modules/vector-search/examples/create-vector-search-index-response.json new file mode 100644 index 000000000..1db73edb0 --- /dev/null +++ b/modules/vector-search/examples/create-vector-search-index-response.json @@ -0,0 +1,5 @@ +{ + "status": "ok", + "name": "vector-sample.color.color-index", + "uuid": "629266a5f4e09384" +} \ No newline at end of file diff --git a/modules/vector-search/examples/run-vector-search-payload.sh b/modules/vector-search/examples/run-vector-search-payload.sh index a0711019f..67409bc40 100644 --- a/modules/vector-search/examples/run-vector-search-payload.sh +++ b/modules/vector-search/examples/run-vector-search-payload.sh @@ -11,7 +11,7 @@ curl -XPOST -H "Content-Type: application/json" \ }, "knn": [ { - "k": 10, + "k": 3, "field": "colorvect_l2", "vector": [ 176, 0, 176 ] } diff --git a/modules/vector-search/examples/run-vector-search-response.json b/modules/vector-search/examples/run-vector-search-response.json new file mode 100644 index 000000000..033f513dd --- /dev/null +++ b/modules/vector-search/examples/run-vector-search-response.json @@ -0,0 +1,125 @@ +{ + "status": { + "total": 1, + "failed": 0, + "successful": 1 + }, + "hits": [ + { + "index": "vector-sample.color.color-index_629266a5f4e09384_4c1c5584", + "id": "#B000B0", + "score": 3.4028234663852886e+38, + "sort": [ + "_score" + ], + "fields": { + "brightness": 72.688, + "color": "dark lavender", + "description": "Dark lavender is a deep, rich color that exudes a sense of mystery and calmness. It envelopes the viewer in its alluring hue, drawing them in with its soothing presence. This color is perfect for creating a sense of depth and intrigue in any space." + }, + "partial_match": true + }, + { + "index": "vector-sample.color.color-index_629266a5f4e09384_4c1c5584", + "id": "#008000", + "score": 0.42046520427629075, + "sort": [ + "_score" + ], + "fields": { + "brightness": 75.136, + "color": "green", + "description": "Green is a color that evokes feelings of freshness and vitality. It is often associated with nature and growth, as it is the color of many plants and trees. The color green can also represent balance and harmony, as it is a combination of the calming blue and energizing yellow. It is a versatile color that can range from a soft pastel to a bold and vibrant hue. Whether it's the lush green of a forest or the crisp green of a freshly cut lawn, this color has a way of invigorating and rejuvenating the senses." + }, + "partial_match": true + }, + { + "index": "vector-sample.color.color-index_629266a5f4e09384_4c1c5584", + "id": "#483D8B", + "score": 0.42046520427629075, + "sort": [ + "_score" + ], + "fields": { + "brightness": 73.181, + "color": "dark slate blue", + "description": "Dark slate blue is a rich and deep color that evokes a sense of mystery and calmness. It envelopes the viewer in its deep hue, creating a soothing and tranquil atmosphere. This color is perfect for creating a sense of depth and intrigue in any space." + }, + "partial_match": true + }, + { + "index": "vector-sample.color.color-index_629266a5f4e09384_4c1c5584", + "id": "#C000C0", + "score": 0.3829836951163303, + "sort": [ + "_score" + ], + "fields": { + "brightness": 79.296, + "color": "magenta", + "description": "Magenta is a vibrant and bold color that is often described as a deep purplish-red. It is a highly saturated color that is eye-catching and demands attention. Magenta is often associated with creativity, passion, and energy. It is a color that exudes confidence and can add a pop of excitement to any design or outfit." + }, + "partial_match": true + }, + { + "index": "vector-sample.color.color-index_629266a5f4e09384_4c1c5584", + "id": "#FF0000", + "score": 0.3810305701163303, + "sort": [ + "_score" + ], + "fields": { + "brightness": 76.245, + "color": "red", + "description": "Red is a vibrant color that evokes feelings of passion and intensity. It is a bold and attention-grabbing color that symbolizes love, energy, and power. Red is often associated with strong emotions and can also represent danger or warning. It is a color that demands attention and can make a statement in any setting." + }, + "partial_match": true + }, + { + "index": "vector-sample.color.color-index_629266a5f4e09384_4c1c5584", + "id": "#A52A2A", + "score": 0.3810305701163303, + "sort": [ + "_score" + ], + "fields": { + "brightness": 78.777, + "color": "brown", + "description": "Brown is a warm and earthy color that often evokes feelings of comfort and stability. It is a rich color that can range from light tan to dark chocolate. Brown is often associated with nature and can be found in the colors of trees, soil, and animals. It is a versatile color that can be used in both casual and formal settings, making it a popular choice in fashion and interior design. Overall, brown is a comforting and grounding color that adds a sense of warmth and coziness to any environment." + }, + "partial_match": true + }, + { + "index": "vector-sample.color.color-index_629266a5f4e09384_4c1c5584", + "id": "#B22222", + "score": 0.3810305701163303, + "sort": [ + "_score" + ], + "fields": { + "brightness": 77.056, + "color": "firebrick", + "description": "Firebrick is a deep, rich red color that evokes images of a blazing fire. It is a warm and intense hue, reminiscent of the glowing embers of a fire. The color is bold and eye-catching, yet also has a sense of warmth and comfort. Firebrick is a powerful and passionate color that demands attention and exudes energy and vitality." + }, + "partial_match": true + }, + { + "index": "vector-sample.color.color-index_629266a5f4e09384_4c1c5584", + "id": "#9400D3", + "score": 0.0004977600796416127, + "sort": [ + "_score" + ], + "fields": { + "brightness": 68.306, + "color": "dark violet", + "description": "Dark violet is a rich and deep color that can be described as enveloping, mysterious, and intense. It is a shade of purple that is darker and more intense than traditional violet. It exudes a sense of mystery and depth, making it a popular choice for creating a dramatic and moody atmosphere. The color is often associated with luxury, royalty, and spirituality. Its deep and intense hue can evoke a sense of power and sophistication. Dark violet is a versatile color that can be used to add depth and drama to any space or design." + } + } + ], + "total_hits": 8, + "cost": 2621, + "max_score": 3.4028234663852886e+38, + "took": 6628491, + "facets": null +} \ No newline at end of file diff --git a/modules/vector-search/pages/create-vector-search-index-rest-api.adoc b/modules/vector-search/pages/create-vector-search-index-rest-api.adoc index 3c1000ce8..131fd3887 100644 --- a/modules/vector-search/pages/create-vector-search-index-rest-api.adoc +++ b/modules/vector-search/pages/create-vector-search-index-rest-api.adoc @@ -70,6 +70,16 @@ NOTE: This sample JSON Vector Search index is the same as the one provided in xr For more information about all the available JSON properties for a Search index, see xref:search:search-index-params.adoc[]. +If the REST API call is successful, the Search Service returns a `200 OK` and the following JSON response: + +[source,json] +---- +include::example$create-vector-search-index-response.json[] +---- + +The `"uuid"` is randomly generated for each Search index you create. +Your own UUID might not match the value shown in the example. + == Next Steps After you create a Search index, you can xref:run-vector-search-rest-api.adoc[] to test your Search index. diff --git a/modules/vector-search/pages/run-vector-search-rest-api.adoc b/modules/vector-search/pages/run-vector-search-rest-api.adoc index aa14917d5..dabd29b7d 100644 --- a/modules/vector-search/pages/run-vector-search-rest-api.adoc +++ b/modules/vector-search/pages/run-vector-search-rest-api.adoc @@ -72,6 +72,13 @@ TIP: For a more complex query, you can copy the `query` object from the example For more information about the available properties for a Search query JSON payload, see xref:search:search-request-params.adoc[]. +If the REST API call is successful, the Search Service returns a `200 OK` and the following JSON response: + +[source,json] +---- +include::example$run-vector-search-response.json[] +---- + == Next Steps If you do not get the search results you were expecting, you can change the JSON definition xref:search:search-index-params.adoc[for your Search index] or change the parameters xref:search:search-request-params.adoc[for your Search query]. From a0cd2fce8cd78b51af8fe9d58d026613d3fdc405 Mon Sep 17 00:00:00 2001 From: Sarah Welton Date: Mon, 18 Nov 2024 16:30:24 -0500 Subject: [PATCH 2/2] [DOC-12253] Adding examples for regular search indexes and updating GeoSpatial/GeoJSON directions to include adding example data + example responses everywhere --- .../create-search-index-response.json | 5 + .../examples/geojson-search-response.json | 104 ++++++++++++++++++ .../geospatial-search-query-geojson.sh | 38 ++++--- .../examples/geospatial-search-response.json | 104 ++++++++++++++++++ .../examples/geospatial-sqlpp-query.sqlpp | 3 + .../search/examples/run-search-response.json | 47 ++++++++ .../pages/create-search-index-rest-api.adoc | 10 ++ modules/search/pages/geo-search-rest-api.adoc | 26 +++++ .../search/pages/simple-search-rest-api.adoc | 7 ++ 9 files changed, 331 insertions(+), 13 deletions(-) create mode 100644 modules/search/examples/create-search-index-response.json create mode 100644 modules/search/examples/geojson-search-response.json create mode 100644 modules/search/examples/geospatial-search-response.json create mode 100644 modules/search/examples/geospatial-sqlpp-query.sqlpp create mode 100644 modules/search/examples/run-search-response.json diff --git a/modules/search/examples/create-search-index-response.json b/modules/search/examples/create-search-index-response.json new file mode 100644 index 000000000..f927a0c34 --- /dev/null +++ b/modules/search/examples/create-search-index-response.json @@ -0,0 +1,5 @@ +{ + "status": "ok", + "name": "travel-sample.inventory.landmark-content-index", + "uuid": "49563a96ea6d3686" +} \ No newline at end of file diff --git a/modules/search/examples/geojson-search-response.json b/modules/search/examples/geojson-search-response.json new file mode 100644 index 000000000..9a1d15c05 --- /dev/null +++ b/modules/search/examples/geojson-search-response.json @@ -0,0 +1,104 @@ +{ + "status": { + "total": 1, + "failed": 0, + "successful": 1 + }, + "hits": [ + { + "index": "travel-sample.inventory.geo-index_642c3761fc0a2c73_4c1c5584", + "id": "landmark_40010", + "score": 0.1332053777355554, + "sort": [ + "_score" + ], + "partial_match": true + }, + { + "index": "travel-sample.inventory.geo-index_642c3761fc0a2c73_4c1c5584", + "id": "landmark_40011", + "score": 0.1332053777355554, + "sort": [ + "_score" + ], + "partial_match": true + }, + { + "index": "travel-sample.inventory.geo-index_642c3761fc0a2c73_4c1c5584", + "id": "landmark_554", + "score": 0.016920542554627847, + "sort": [ + "_score" + ], + "partial_match": true + }, + { + "index": "travel-sample.inventory.geo-index_642c3761fc0a2c73_4c1c5584", + "id": "landmark_11323", + "score": 0.016920542554627847, + "sort": [ + "_score" + ], + "partial_match": true + }, + { + "index": "travel-sample.inventory.geo-index_642c3761fc0a2c73_4c1c5584", + "id": "landmark_37316", + "score": 0.016920542554627847, + "sort": [ + "_score" + ], + "partial_match": true + }, + { + "index": "travel-sample.inventory.geo-index_642c3761fc0a2c73_4c1c5584", + "id": "landmark_581", + "score": 0.016920542554627847, + "sort": [ + "_score" + ], + "partial_match": true + }, + { + "index": "travel-sample.inventory.geo-index_642c3761fc0a2c73_4c1c5584", + "id": "landmark_15903", + "score": 0.016920542554627847, + "sort": [ + "_score" + ], + "partial_match": true + }, + { + "index": "travel-sample.inventory.geo-index_642c3761fc0a2c73_4c1c5584", + "id": "landmark_570", + "score": 0.016920542554627847, + "sort": [ + "_score" + ], + "partial_match": true + }, + { + "index": "travel-sample.inventory.geo-index_642c3761fc0a2c73_4c1c5584", + "id": "landmark_566", + "score": 0.016920542554627847, + "sort": [ + "_score" + ], + "partial_match": true + }, + { + "index": "travel-sample.inventory.geo-index_642c3761fc0a2c73_4c1c5584", + "id": "landmark_22565", + "score": 0.016920542554627847, + "sort": [ + "_score" + ], + "partial_match": true + } + ], + "total_hits": 257, + "cost": 35339, + "max_score": 0.1332053777355554, + "took": 10019436, + "facets": null +} \ No newline at end of file diff --git a/modules/search/examples/geospatial-search-query-geojson.sh b/modules/search/examples/geospatial-search-query-geojson.sh index d7d89c83f..05a623ab0 100644 --- a/modules/search/examples/geospatial-search-query-geojson.sh +++ b/modules/search/examples/geospatial-search-query-geojson.sh @@ -5,33 +5,45 @@ curl -s -XPUT -H "Content-Type: application/json" \ "field": "geojson", "geometry": { "shape": { - "type": "Polygon", "coordinates": [ + [ [ + -3.272607322511618, + 53.94443025530833 + ], [ - 0.47482593026924746, - 51.31232878073189 + -3.369506040138134, + 53.2576036482846 ], [ - 0.6143265647863245, - 51.31232878073189 + -1.531900030030954, + 53.352538254565076 ], [ - 0.6143265647863245, - 51.384000374770466 + -0.08209172686298416, + 53.568703110993994 ], [ - 0.47482593026924746, - 51.384000374770466 + -0.4648577685729265, + 53.86797332814126 ], [ - 0.47482593026924746, - 51.31232878073189 - ] + -1.612712602375666, + 54.022352820673774 + ], + [ + -2.2803785770867933, + 54.05470383755585 + ], + [ + -3.272607322511618, + 53.94443025530833 ] ] + ], + "type": "Polygon" }, "relation": "within" } } - } \ No newline at end of file + }' \ No newline at end of file diff --git a/modules/search/examples/geospatial-search-response.json b/modules/search/examples/geospatial-search-response.json new file mode 100644 index 000000000..3f5bfd254 --- /dev/null +++ b/modules/search/examples/geospatial-search-response.json @@ -0,0 +1,104 @@ +{ + "status": { + "total": 1, + "failed": 0, + "successful": 1 + }, + "hits": [ + { + "index": "travel-sample.inventory.geo-index_78125822b3de7be3_4c1c5584", + "id": "landmark_17411", + "score": 0.009274733001968816, + "sort": [ + " \u0001?E#9\u003eN\u000c\"e" + ], + "partial_match": true + }, + { + "index": "travel-sample.inventory.geo-index_78125822b3de7be3_4c1c5584", + "id": "landmark_17409", + "score": 0.009274733001968816, + "sort": [ + " \u0001?O~i*(kD," + ], + "partial_match": true + }, + { + "index": "travel-sample.inventory.geo-index_78125822b3de7be3_4c1c5584", + "id": "landmark_17403", + "score": 0.009274733001968816, + "sort": [ + " \u0001?Sg*|/t\u001f\u0002" + ], + "partial_match": true + }, + { + "index": "travel-sample.inventory.geo-index_78125822b3de7be3_4c1c5584", + "id": "landmark_17410", + "score": 0.009274733001968816, + "sort": [ + " \u0001?Z3T6 \u0010\u0019@" + ], + "partial_match": true + }, + { + "index": "travel-sample.inventory.geo-index_78125822b3de7be3_4c1c5584", + "id": "landmark_17412", + "score": 0.009274733001968816, + "sort": [ + " \u0001?]-\u000fm?\u000b\u0014#" + ], + "partial_match": true + }, + { + "index": "travel-sample.inventory.geo-index_78125822b3de7be3_4c1c5584", + "id": "landmark_17408", + "score": 0.009274733001968816, + "sort": [ + " \u0001?^DV7\u0014t:^" + ], + "partial_match": true + }, + { + "index": "travel-sample.inventory.geo-index_78125822b3de7be3_4c1c5584", + "id": "landmark_17406", + "score": 0.009274733001968816, + "sort": [ + " \u0001?_\u003c\u00009\u001eW\u0013\u0012" + ], + "partial_match": true + }, + { + "index": "travel-sample.inventory.geo-index_78125822b3de7be3_4c1c5584", + "id": "landmark_17397", + "score": 0.009274733001968816, + "sort": [ + " \u0001?c\u001cx\u0010n\u0016Wl" + ], + "partial_match": true + }, + { + "index": "travel-sample.inventory.geo-index_78125822b3de7be3_4c1c5584", + "id": "landmark_17407", + "score": 0.009274733001968816, + "sort": [ + " \u0001?c!7\u0001@SwS" + ], + "partial_match": true + }, + { + "index": "travel-sample.inventory.geo-index_78125822b3de7be3_4c1c5584", + "id": "landmark_17391", + "score": 0.009274733001968816, + "sort": [ + " \u0001?dgzZ[\u0007;y" + ], + "partial_match": true + } + ], + "total_hits": 640, + "cost": 157249, + "max_score": 0.17106779096990765, + "took": 15349178, + "facets": null +} \ No newline at end of file diff --git a/modules/search/examples/geospatial-sqlpp-query.sqlpp b/modules/search/examples/geospatial-sqlpp-query.sqlpp new file mode 100644 index 000000000..57642e8ae --- /dev/null +++ b/modules/search/examples/geospatial-sqlpp-query.sqlpp @@ -0,0 +1,3 @@ +UPDATE `travel-sample`.inventory.landmark + SET geojson = { "type": "Point", "coordinates": [geo.lon, geo.lat] } + WHERE geo IS NOT null; \ No newline at end of file diff --git a/modules/search/examples/run-search-response.json b/modules/search/examples/run-search-response.json new file mode 100644 index 000000000..deeed06b2 --- /dev/null +++ b/modules/search/examples/run-search-response.json @@ -0,0 +1,47 @@ +{ + "status": { + "total": 1, + "failed": 0, + "successful": 1 + }, + "hits": [ + { + "index": "travel-sample.inventory.landmark-content-index_49563a96ea6d3686_4c1c5584", + "id": "landmark_4428", + "score": 2.425509689250102, + "sort": [ + "_score" + ], + "fields": { + "content": "serves fresh food at very reasonable prices - view of stoney beach with herons" + } + }, + { + "index": "travel-sample.inventory.landmark-content-index_49563a96ea6d3686_4c1c5584", + "id": "landmark_26385", + "score": 1.6270812956011347, + "sort": [ + "_score" + ], + "fields": { + "content": "Burgers, seafood, and other simple but tasty meals right at the harbor. You can take your food around the corner to sit on the beach or the sea wall and enjoy the ocean view while you eat." + } + }, + { + "index": "travel-sample.inventory.landmark-content-index_49563a96ea6d3686_4c1c5584", + "id": "landmark_38035", + "score": 1.1962539437368078, + "sort": [ + "_score" + ], + "fields": { + "content": "Famous for "the Blue Lady", a ghost rumored to haunt the premises, the Moss Beach distillery offers a full menu, Sunday brunch, drinks, and a tremendous ocean view with comfortable fire pits. Happy hour Mon-Fri from 5PM to 7PM offers half-priced drinks and a discounted food menu." + } + } + ], + "total_hits": 3, + "cost": 150479, + "max_score": 2.425509689250102, + "took": 1441203, + "facets": null +} \ No newline at end of file diff --git a/modules/search/pages/create-search-index-rest-api.adoc b/modules/search/pages/create-search-index-rest-api.adoc index cf52e6b81..244bb4af7 100644 --- a/modules/search/pages/create-search-index-rest-api.adoc +++ b/modules/search/pages/create-search-index-rest-api.adoc @@ -69,6 +69,16 @@ IMPORTANT: XATTRs mappings are only available in Couchbase Server version 7.6.2 For more information about the available JSON properties for a Search index, see xref:search-index-params.adoc[]. +If the REST API call is successful, the Search Service returns a `200 OK` and the following JSON response: + +[source,json] +---- +include::example$create-search-index-response.json[] +---- + +The `"uuid"` is randomly generated for each Search index you create. +Your own UUID might not match the value shown in the example. + == Next Steps After you create a Search index, you can xref:simple-search-rest-api.adoc[] to test your Search index. diff --git a/modules/search/pages/geo-search-rest-api.adoc b/modules/search/pages/geo-search-rest-api.adoc index dcd9f3a40..a551dc640 100644 --- a/modules/search/pages/geo-search-rest-api.adoc +++ b/modules/search/pages/geo-search-rest-api.adoc @@ -75,8 +75,26 @@ For example, the following query searches a geospatial field, `geo`, for any loc include::example$geospatial-search-query.sh[] ---- +If the REST API call is successful, the Search Service returns a `200 OK`. +Using the `landmark` collection, the query can return the following JSON response: + +[source,json] +---- +include::example$geospatial-search-response.json[] +---- + === Example: GeoJSON Query +[TIP] +==== +To run the following example against the `landmark` collection in the `travel-sample` dataset, run the following {sqlpp} query from the xref:tools:query-workbench.adoc[Query Workbench]: + +[source,sqlpp] +---- +include::example$geospatial-sqlpp-query.sqlpp[] +---- +==== + For example, the following query searches a geospatial field, `geojson`, for any locations within a defined shape with a xref:search-request-params.adoc#geojson-queries-polygon[Polygon GeoJSON Query]: [source,console] @@ -84,6 +102,14 @@ For example, the following query searches a geospatial field, `geojson`, for any include::example$geospatial-search-query-geojson.sh[] ---- +If the REST API call is successful, the Search Service returns a `200 OK`. +Using the `landmark` collection, the query can return the following JSON response: + +[source,json] +---- +include::example$geojson-search-response.json[] +---- + == Next Steps You can xref:customize-index.adoc[customize your Search index] to improve search results and performance. diff --git a/modules/search/pages/simple-search-rest-api.adoc b/modules/search/pages/simple-search-rest-api.adoc index 5e9b30628..6131ff6c9 100644 --- a/modules/search/pages/simple-search-rest-api.adoc +++ b/modules/search/pages/simple-search-rest-api.adoc @@ -61,6 +61,13 @@ include::example$run-search-payload.sh[] For more information about the available properties for a Search query JSON payload, see xref:search-request-params.adoc[]. +If the REST API call is successful, the Search Service returns a `200 OK` and the following JSON response: + +[source,json] +---- +include::example$run-search-response.json[] +---- + == Next Steps If you do not get the search results you were expecting, you can change the JSON payload xref:search-index-params.adoc[for your Search index] or xref:search-request-params.adoc[for your Search query].