Update client for 1.14 (#218)

* update protos, fix strictmode

* add formula builder and expression constructors

* add builder for decay params expression

* add helper fns for StrictModeConfigBuilder

* add builder for StrictModeMultivectorConfigBuilder

* add builder for StrictModeSparseConfig

* clippy

* additional helpers

* validate docs snippets

* clippy

* helper: set all defaults in formula

* move snippets to query_points.rs

* no option for mandatory fields

* pass HardwareUsage ownership

* builders for score variables

* Use new score function in tests

---------

Co-authored-by: timvisee <[email protected]>

Author: coszio

proto/collections.proto

@@ -342,6 +342,25 @@ message StrictModeConfig {
   optional uint64 max_collection_payload_size_bytes = 13;
   optional uint64 filter_max_conditions = 14;
   optional uint64 condition_max_size = 15;
+  optional StrictModeMultivectorConfig multivector_config = 16;
+  optional StrictModeSparseConfig sparse_config = 17;
+  optional uint64 max_points_count = 18;
+}
+
+message StrictModeSparseConfig {
+  map<string, StrictModeSparse> sparse_config = 1;
+}
+
+message StrictModeSparse {
+  optional uint64 max_length = 10;
+}
+
+message StrictModeMultivectorConfig {
+  map<string, StrictModeMultivector> multivector_config = 1;
+}
+
+message StrictModeMultivector {
+  optional uint64 max_vectors  = 1;
 }
 
 message CreateCollection {

proto/points.proto

@@ -425,6 +425,10 @@ enum RecommendStrategy {
   // examples, its score is then chosen from the `max(max_pos_score, max_neg_score)`.
   // If the `max_neg_score` is chosen then it is squared and negated.
   BestScore = 1;
+  
+  // Uses custom search objective. Compares against all inputs, sums all the scores.
+  // Scores against positive vectors are added, against negatives are subtracted.
+  SumScores = 2;
 }
 
 message LookupLocation {
@@ -572,6 +576,70 @@ enum Sample {
     Random = 0;
 }
 
+message Formula {
+    Expression expression = 1;
+    map<string, Value> defaults = 2;
+}
+
+message Expression {
+    oneof variant {
+        float constant = 1;
+        string variable = 2; // Payload key or reference to score.
+        Condition condition = 3; // Payload condition. If true, becomes 1.0; otherwise 0.0
+        GeoDistance geo_distance = 4; // Geographic distance in meters
+        string datetime = 5; // Date-time constant
+        string datetime_key = 6; // Payload key with date-time values
+        MultExpression mult = 7; // Multiply
+        SumExpression sum = 8; // Sum
+        DivExpression div = 9; // Divide
+        Expression neg = 10; // Negate
+        Expression abs = 11; // Absolute value
+        Expression sqrt = 12; // Square root
+        PowExpression pow = 13; // Power
+        Expression exp = 14; // Exponential
+        Expression log10 = 15; // Logarithm
+        Expression ln = 16; // Natural logarithm
+        DecayParamsExpression exp_decay = 17; // Exponential decay
+        DecayParamsExpression gauss_decay = 18; // Gaussian decay
+        DecayParamsExpression lin_decay = 19; // Linear decay
+    }
+}
+
+message GeoDistance {
+    GeoPoint origin = 1;
+    string to = 2;
+}
+
+message MultExpression {
+    repeated Expression mult = 1;
+}
+
+message SumExpression {
+    repeated Expression sum = 1;
+}
+
+message DivExpression {
+    Expression left = 1;
+    Expression right = 2;
+    optional float by_zero_default = 3;
+}
+
+message PowExpression {
+    Expression base = 1;
+    Expression exponent = 2;
+}
+
+message DecayParamsExpression {
+    // The variable to decay
+    Expression x = 1; 
+    // The target value to start decaying from. Defaults to 0.
+    optional Expression target = 2; 
+    // The scale factor of the decay, in terms of `x`. Defaults to 1.0. Must be a non-zero positive number.
+    optional float scale = 3; 
+    // The midpoint of the decay. Defaults to 0.5. Output will be this value when `|x - target| == scale`.
+    optional float midpoint = 4; 
+}
+
 message Query {
   oneof variant {
     VectorInput nearest = 1; // Find the nearest neighbors to this vector.
@@ -581,6 +649,7 @@ message Query {
     OrderBy order_by = 5; // Order the points by a payload field.
     Fusion fusion = 6; // Fuse the results of multiple prefetches.
     Sample sample = 7; // Sample points from the collection.
+    Formula formula = 8; // Score boosting via an arbitrary formula
   }
 }
 
@@ -761,6 +830,7 @@ message UpdateBatchPoints {
 message PointsOperationResponse {
   UpdateResult result = 1;
   double time = 2; // Time spent to process
+  optional HardwareUsage usage = 3;
 }
 
 message UpdateResult {
@@ -864,6 +934,7 @@ message ScrollResponse {
   optional PointId next_page_offset = 1; // Use this offset for the next query
   repeated RetrievedPoint result = 2;
   double time = 3; // Time spent to process
+  optional HardwareUsage usage = 4;
 }
 
 message CountResult {
@@ -882,6 +953,7 @@ message RetrievedPoint {
 message GetResponse {
   repeated RetrievedPoint result = 1;
   double time = 2; // Time spent to process
+  optional HardwareUsage usage = 3;
 }
 
 message RecommendResponse {
@@ -994,6 +1066,8 @@ message FieldCondition {
   ValuesCount values_count = 6; // Check number of values for a specific field
   GeoPolygon geo_polygon = 7; // Check if geo point is within a given polygon
   DatetimeRange datetime_range = 8; // Check if datetime is within a given range
+  optional bool is_empty = 9; // Check if field is empty
+  optional bool is_null = 10; // Check if field is null
 }
 
 message Match {
@@ -1098,6 +1172,10 @@ message GeoPoint {
 
 message HardwareUsage {
   uint64 cpu = 1;
-  uint64 io_read = 2;
-  uint64 io_write = 3;
+  uint64 payload_io_read = 2;
+  uint64 payload_io_write = 3;
+  uint64 payload_index_io_read = 4;
+  uint64 payload_index_io_write = 5;
+  uint64 vector_io_read = 6;
+  uint64 vector_io_write = 7;
 }

src/builders/decay_params_expression_builder.rs

@@ -0,0 +1,93 @@
+use crate::qdrant::*;
+
+/// Builder for the DecayParamsExpression struct, which represents parameters for decay functions.
+///
+/// Decay functions (exponential, Gaussian, linear) are used in scoring to create a decay effect
+/// based on distance from a target value.
+pub struct DecayParamsExpressionBuilder {
+    /// The variable to decay
+    pub(crate) x: Expression,
+    /// The target value to start decaying from. Defaults to 0.
+    pub(crate) target: Option<Expression>,
+    /// The scale factor of the decay, in terms of `x`. Defaults to 1.0. Must be a non-zero positive number.
+    pub(crate) scale: Option<f32>,
+    /// The midpoint of the decay. Defaults to 0.5. Output will be this value when `|x - target| == scale`.
+    pub(crate) midpoint: Option<f32>,
+}
+
+impl DecayParamsExpressionBuilder {
+    /// Creates a new DecayParamsExpressionBuilder with the variable to decay.
+    /// This is the only required parameter.
+    pub fn new<E: Into<Expression>>(x: E) -> Self {
+        Self {
+            x: x.into(),
+            target: None,
+            scale: None,
+            midpoint: None,
+        }
+    }
+
+    /// Sets the variable to decay. This is the value that will be compared to the target.
+    pub fn x<E: Into<Expression>>(self, x: E) -> Self {
+        let mut new = self;
+        new.x = x.into();
+        new
+    }
+
+    /// Sets the target value to start decaying from. Defaults to 0 if not specified.
+    /// The decay is at its maximum (1.0) when x equals the target.
+    pub fn target<E: Into<Expression>>(self, target: E) -> Self {
+        let mut new = self;
+        new.target = Some(target.into());
+        new
+    }
+
+    /// Sets the scale factor of the decay, in terms of `x`. Defaults to 1.0 if not specified.
+    /// Must be a non-zero positive number.
+    /// This controls how quickly the function decays away from the target value.
+    pub fn scale(self, scale: f32) -> Self {
+        let mut new = self;
+        new.scale = Some(scale);
+        new
+    }
+
+    /// Sets the midpoint of the decay. Defaults to 0.5 if not specified.
+    /// The output will be this value when the distance between x and target equals the scale.
+    pub fn midpoint(self, midpoint: f32) -> Self {
+        let mut new = self;
+        new.midpoint = Some(midpoint);
+        new
+    }
+
+    fn build_inner(self) -> Result<DecayParamsExpression, std::convert::Infallible> {
+        Ok(DecayParamsExpression {
+            x: Some(Box::new(self.x)),
+            target: self.target.map(Box::new),
+            scale: self.scale,
+            midpoint: self.midpoint,
+        })
+    }
+}
+
+impl From<DecayParamsExpressionBuilder> for DecayParamsExpression {
+    fn from(value: DecayParamsExpressionBuilder) -> Self {
+        value.build_inner().unwrap_or_else(|_| {
+            panic!(
+                "Failed to convert {0} to {1}",
+                "DecayParamsExpressionBuilder", "DecayParamsExpression"
+            )
+        })
+    }
+}
+
+impl DecayParamsExpressionBuilder {
+    /// Builds the DecayParamsExpression from this builder.
+    pub fn build(self) -> DecayParamsExpression {
+        self.build_inner().unwrap_or_else(|_| {
+            panic!(
+                "Failed to build {0} into {1}",
+                "DecayParamsExpressionBuilder", "DecayParamsExpression"
+            )
+        })
+    }
+}

src/builders/formula_builder.rs

@@ -0,0 +1,65 @@
+use std::collections::HashMap;
+
+use crate::qdrant::*;
+
+/// Builder for the Formula struct, which represents a scoring formula for points.
+///
+/// The Formula struct is used to define custom scoring expressions and default values.
+pub struct FormulaBuilder {
+    /// The expression that defines how to score points.
+    pub(crate) expression: Expression,
+    /// Default values to use for undefined variables in the expression.
+    pub(crate) defaults: HashMap<String, Value>,
+}
+
+impl FormulaBuilder {
+    /// Sets the expression for the formula.
+    pub fn new<E: Into<Expression>>(expression: E) -> Self {
+        Self {
+            expression: expression.into(),
+            defaults: Default::default(),
+        }
+    }
+
+    pub fn expression<E: Into<Expression>>(self, value: E) -> Self {
+        let mut new = self;
+        new.expression = value.into();
+        new
+    }
+
+    /// Sets all default values for the formula.
+    pub fn defaults(mut self, defaults: HashMap<String, Value>) -> Self {
+        self.defaults = defaults;
+        self
+    }
+
+    /// Adds a single default value to the formula's defaults.
+    pub fn add_default<K: Into<String>, V: Into<Value>>(self, key: K, value: V) -> Self {
+        let mut new = self;
+        new.defaults.insert(key.into(), value.into());
+        new
+    }
+
+    fn build_inner(self) -> Result<Formula, std::convert::Infallible> {
+        Ok(Formula {
+            expression: Some(self.expression),
+            defaults: self.defaults,
+        })
+    }
+}
+
+impl From<FormulaBuilder> for Formula {
+    fn from(value: FormulaBuilder) -> Self {
+        value
+            .build_inner()
+            .unwrap_or_else(|_| panic!("Failed to convert {0} to {1}", "FormulaBuilder", "Formula"))
+    }
+}
+
+impl FormulaBuilder {
+    /// Builds the desired Formula type.
+    pub fn build(self) -> Formula {
+        self.build_inner()
+            .unwrap_or_else(|_| panic!("Failed to build {0} into {1}", "FormulaBuilder", "Formula"))
+    }
+}

src/builders/mod.rs

@@ -34,6 +34,12 @@ pub use binary_quantization_builder::BinaryQuantizationBuilder;
 mod strict_mode_config_builder;
 pub use strict_mode_config_builder::StrictModeConfigBuilder;
 
+mod strict_mode_multivector_config_builder;
+pub use strict_mode_multivector_config_builder::StrictModeMultivectorConfigBuilder;
+
+mod strict_mode_sparse_config_builder;
+pub use strict_mode_sparse_config_builder::StrictModeSparseConfigBuilder;
+
 mod update_collection_builder;
 pub use update_collection_builder::UpdateCollectionBuilder;
 
@@ -199,6 +205,12 @@ pub use query_batch_points_builder::QueryBatchPointsBuilder;
 mod query_point_groups_builder;
 pub use query_point_groups_builder::QueryPointGroupsBuilder;
 
+mod formula_builder;
+pub use formula_builder::FormulaBuilder;
+
+mod decay_params_expression_builder;
+pub use decay_params_expression_builder::DecayParamsExpressionBuilder;
+
 mod facet_counts_builder;
 pub use facet_counts_builder::FacetCountsBuilder;