diff --git a/documentation/user/en/query/requirements/examples/histogram/attribute-histogram-optimized.evitaql.json.md b/documentation/user/en/query/requirements/examples/histogram/attribute-histogram-optimized.evitaql.json.md new file mode 100644 index 000000000..4c624689e --- /dev/null +++ b/documentation/user/en/query/requirements/examples/histogram/attribute-histogram-optimized.evitaql.json.md @@ -0,0 +1,48 @@ +```json +{ + "histograms": { + "width": { + "buckets": [ + { + "occurrences": 1291, + "requested": true, + "threshold": 15.90 + }, + { + "index": 1, + "occurrences": 210, + "requested": true, + "threshold": 97.92 + }, + { + "index": 2, + "occurrences": 1876, + "requested": true, + "threshold": 179.94 + }, + { + "index": 3, + "occurrences": 531, + "requested": true, + "threshold": 261.96 + }, + { + "index": 4, + "occurrences": 2, + "requested": true, + "threshold": 343.98 + }, + { + "index": 5, + "occurrences": 1, + "requested": true, + "threshold": 426.00 + } + ], + "max": 508.00, + "min": 15.90, + "overallCount": 3911 + } + } +} +``` \ No newline at end of file diff --git a/documentation/user/en/query/requirements/examples/histogram/price-histogram-optimized.evitaql.json.md b/documentation/user/en/query/requirements/examples/histogram/price-histogram-optimized.evitaql.json.md new file mode 100644 index 000000000..1854346f9 --- /dev/null +++ b/documentation/user/en/query/requirements/examples/histogram/price-histogram-optimized.evitaql.json.md @@ -0,0 +1,49 @@ +```json +{ + "buckets": [ + { + "occurrences": 3, + "requested": true, + "threshold": 59.00 + }, + { + "index": 1, + "occurrences": 2, + "requested": true, + "threshold": 72.00 + }, + { + "index": 2, + "occurrences": 3, + "requested": true, + "threshold": 85.00 + }, + { + "index": 3, + "occurrences": 1, + "requested": true, + "threshold": 98.00 + }, + { + "index": 4, + "occurrences": 6, + "requested": true, + "threshold": 111.00 + }, + { + "index": 5, + "requested": true, + "threshold": 124.00 + }, + { + "index": 6, + "occurrences": 3, + "requested": true, + "threshold": 137.00 + } + ], + "max": 150.00, + "min": 59.00, + "overallCount": 18 +} +``` \ No newline at end of file diff --git a/documentation/user/en/query/requirements/histogram.md b/documentation/user/en/query/requirements/histogram.md index 3839e74b1..39c221b38 100644 --- a/documentation/user/en/query/requirements/histogram.md +++ b/documentation/user/en/query/requirements/histogram.md @@ -25,13 +25,17 @@ The histogram data structure is optimized for frontend rendering. It contains th - **`min`** - the minimum value of the attribute in the current filter context - **`max`** - the maximum value of the attribute in the current filter context - **`overallCount`** - the number of elements whose attribute value falls into any of the buckets (it's basically a sum of all bucket occurrences) -- **`buckets`** - an array of buckets, each of which contains the following fields: +- **`buckets`** - an *sorted* array of buckets, each of which contains the following fields: - **`index`** - the index of the bucket in the array - - **`threshold`** - the minimum value of the attribute in the bucket + - **`threshold`** - the minimum value of the attribute in the bucket, the maximum value is the threshold of the next bucket (or `max` for the last bucket) - **`occurrences`** - the number of elements whose attribute value falls into the bucket - - **`requested`** - contains `true` if the query contained [attributeBetween](../filtering/comparable.md#attribute-between) - or [priceBetween](../filtering/price.md#price-between) constraint for particular attribute / price - and the bucket threshold lies within the range (inclusive) of the constraint + - **`requested`**: + - contains `true` if the query didn't contain any [attributeBetween](../filtering/comparable.md#attribute-between) + or [priceBetween](../filtering/price.md#price-between) constraints + - contains `true` if the query contained [attributeBetween](../filtering/comparable.md#attribute-between) + or [priceBetween](../filtering/price.md#price-between) constraint for particular attribute / price + and the bucket threshold lies within the range (inclusive) of the constraint + - contains `false` otherwise ## Attribute histogram @@ -114,6 +118,8 @@ The histogram result in JSON format is a bit more verbose, but it's still quite + + ### Attribute histogram contents optimization During user testing, we found that histograms with scarce data are not very useful. Besides the fact that they don't @@ -133,9 +139,21 @@ To demonstrate the optimization of the histogram, we will use the following exam The simplified result looks like this: +[The result of optimized `width` attribute histogram](/documentation/user/en/query/requirements/examples/histogram/attribute-histogram-optimized.evitaql.string.md) + + + + + +##### The optimized result of `width` and `height` attribute histogram in JSON format + + + +The optimized histogram result in JSON format is a bit more verbose, but it's still quite readable: + -[The result of optimized `width` attribute histogram](/documentation/user/en/query/requirements/examples/histogram/attribute-histogram-optimized.evitaql.string.md) +[The result of optimized `width` attribute histogram](/documentation/user/en/query/requirements/examples/histogram/attribute-histogram-optimized.evitaql.json.md) @@ -149,6 +167,8 @@ The simplified result looks like this: + + As you can see, the number of buckets has been adjusted to fit the data, contrary to the default behavior. ## Price histogram @@ -249,9 +269,21 @@ To demonstrate the optimization of the histogram, we will use the following exam The simplified result looks like this: +[The result of optimized price histogram](/documentation/user/en/query/requirements/examples/histogram/price-histogram-optimized.evitaql.string.md) + + + + + +##### The result of optimized price histogram in JSON format + + + +The optimized histogram result in JSON format is a bit more verbose, but it's still quite readable: + -[The result of optimized price histogram](/documentation/user/en/query/requirements/examples/histogram/price-histogram-optimized.evitaql.string.md) +[The result of optimized price histogram](/documentation/user/en/query/requirements/examples/histogram/price-histogram-optimized.evitaql.json.md) @@ -265,4 +297,6 @@ The simplified result looks like this: + + As you can see, the number of buckets has been adjusted to fit the data, contrary to the default behavior. \ No newline at end of file diff --git a/evita_functional_tests/src/test/java/io/evitadb/documentation/UserDocumentationTest.java b/evita_functional_tests/src/test/java/io/evitadb/documentation/UserDocumentationTest.java index 1bc5c89c5..9061947f9 100644 --- a/evita_functional_tests/src/test/java/io/evitadb/documentation/UserDocumentationTest.java +++ b/evita_functional_tests/src/test/java/io/evitadb/documentation/UserDocumentationTest.java @@ -6,7 +6,7 @@ * | __/\ V /| | || (_| | |_| | |_) | * \___| \_/ |_|\__\__,_|____/|____/ * - * Copyright (c) 2023 + * Copyright (c) 2023-2024 * * Licensed under the Business Source License, Version 1.1 (the "License"); * you may not use this file except in compliance with the License. @@ -456,9 +456,9 @@ Stream testSingleFileDocumentation() { Stream testSingleFileDocumentationAndCreateOtherLanguageSnippets() { return this.createTests( Environment.DEMO_SERVER, - getRootDirectory().resolve("documentation/user/en/query/requirements/facet.md"), + getRootDirectory().resolve("documentation/user/en/query/requirements/histogram.md"), ExampleFilter.values(), - CreateSnippets.MARKDOWN, /*CreateSnippets.JAVA, CreateSnippets.GRAPHQL, */CreateSnippets.REST/*, CreateSnippets.CSHARP*/ + CreateSnippets.MARKDOWN, /*CreateSnippets.JAVA,*/ CreateSnippets.GRAPHQL, CreateSnippets.REST/*, CreateSnippets.CSHARP*/ ).stream(); }