[GLE-8861] feat(vector): built-in TG function for pairwise vector emb…

…edding;

gds/vector/cosine_distance.gsql

@@ -0,0 +1,56 @@
+CREATE FUNCTION gds.vector.cosine_distance(list<double> list1, list<double> list2) RETURNS(float) {
+
+  /*
+  First Author: Jue Yuan
+  First Commit Date:  Nov 27, 2024 
+
+  Recent Author: Jue Yuan
+  Recent Commit Date: Nov 27, 2024 
+
+  Maturity:
+      alpha
+
+  Description:
+      Calculates the cosine distance between two vectors represented as lists of doubles.
+      The cosine distance is derived from the cosine similarity and provides a measure of the angle
+      between two non-zero vectors in a multi-dimensional space. A distance of 0 indicates identical
+      vectors, while a distance of 1 indicates orthogonal (maximally dissimilar) vectors.
+
+  Parameters:
+      list<double> list1:
+          The first vector as a list of double values.
+      list<double> list2:
+          The second vector as a list of double values.
+
+  Returns:
+      float:
+          The cosine distance between the two input vectors.
+  Exceptions:
+      list_size_mismatch (90000):
+          Raised when the input lists are not of equal size.
+
+  Logic Overview:
+      Validates that both input vectors have the same length.
+      Computes the inner (dot) product of the two vectors.
+      Calculates the magnitudes (Euclidean norms) of both vectors.
+      Returns the cosine distance as 1 - (inner product) / (product of magnitudes).
+
+  Use Case:
+      This function is commonly used in machine learning, natural language processing,
+      and information retrieval tasks to quantify the similarity between vector representations,
+      such as word embeddings or document feature vectors.
+  */
+
+  EXCEPTION list_size_mismatch (90000);
+  ListAccum<double> @@myList1 = list1;
+  ListAccum<double> @@myList2 = list2;
+
+  IF (@@myList1.size() != @@myList2.size()) THEN
+    RAISE list_size_mismatch ("Two lists provided for gds.vector.cosine_distance have different sizes.");
+  END;
+
+  double innerP = inner_product(@@myList1, @@myList2);
+  double v1_magn = sqrt(inner_product(@@myList1, @@myList1));
+  double v2_magn = sqrt(inner_product(@@myList2, @@myList2));
+  RETURN (1 - innerP / (v1_magn * v2_magn));
+}

gds/vector/dimension_count.gsql

@@ -0,0 +1,37 @@
+CREATE FUNCTION gds.vector.dimension_count(list<double> list1) RETURNS(int) {
+
+  /*
+  First Author: Jue Yuan
+  First Commit Date:  Nov 27, 2024 
+
+  Recent Author: Jue Yuan
+  Recent Commit Date: Nov 27, 2024 
+
+  Maturity:
+      alpha
+
+  Description:
+      Returns the number of dimensions (elements) in a given vector, represented as a list of double values.
+      This function is useful for determining the size or dimensionality of input vectors in mathematical
+      and data processing operations.
+
+  Parameters:
+      list<double> list1:
+          The input vector as a list of double values.
+
+  Returns:
+      int:
+          The number of elements (dimensions) in the input vector.
+
+  Logic Overview:
+      Accepts a list of double values as input.
+      Calculates the size of the list, which corresponds to the number of dimensions.
+      Returns the size as an integer.
+  Use Case:
+      This function is valuable in vector-based computations, such as machine learning or data analysis tasks,
+      where understanding the dimensionality of vectors is crucial for validation, preprocessing, or compatibility checks.
+  */
+
+  ListAccum<double> @@myList1 = list1;
+  RETURN @@myList1.size();
+}

gds/vector/distance.gsql

@@ -0,0 +1,85 @@
+CREATE FUNCTION gds.vector.distance(list<double> list1, list<double> list2, string metric) RETURNS(float) {
+
+  /*
+  First Author: Jue Yuan
+  First Commit Date:  Nov 27, 2024 
+
+  Recent Author: Jue Yuan
+  Recent Commit Date: Nov 27, 2024 
+
+  Maturity:
+      alpha
+
+  Description:
+      Calculates the distance between two vectors represented as lists of double values,
+      based on a specified distance metric. This function supports multiple metrics,
+      allowing for flexible similarity or dissimilarity measurements in various computational tasks.
+
+  Parameters:
+      list<double> list1:
+          The first vector as a list of double values.
+      list<double> list2:
+          The second vector as a list of double values.
+      string metric:
+          The distance metric to use. Supported metrics are:
+              "cosine": Cosine distance
+              "euclidean": Euclidean distance
+              "ip": Inner product (dot product)
+  Returns:
+      float:
+          The computed distance between the two input vectors based on the specified metric.
+
+  Exceptions:
+      list_size_mismatch (90000):
+          Raised when the input vectors are not of equal size.
+      invalid_metric_type (90001):
+          Raised when an unsupported distance metric is provided.
+
+  Logic Overview:
+      Input Validation:
+          Ensures both vectors have the same size.
+  Metric Handling:
+      Cosine Distance:
+          Calculated as 1 - (inner product of vectors) / (product of magnitudes).
+      Euclidean Distance:
+          Computes the square root of the sum of squared differences between corresponding elements.
+      Inner Product:
+          Directly computes the dot product of the two vectors.
+
+  Error Handling:
+      Raises an exception if the provided metric is invalid.
+
+  Use Case:
+      This function is essential for machine learning, data science, and information retrieval applications,
+      where distance or similarity calculations between vector representations (such as embeddings or feature vectors) are required.
+  */
+
+  EXCEPTION list_size_mismatch (90000);
+  EXCEPTION invalid_metric_type (90001);
+  ListAccum<double> @@myList1 = list1;
+  ListAccum<double> @@myList2 = list2;
+
+  IF (@@myList1.size() != @@myList2.size()) THEN
+    RAISE list_size_mismatch ("Two lists provided for gds.vector.distance have different sizes.");
+  END;
+
+  SumAccum<float> @@myResult;
+  SumAccum<float> @@sqrSum;
+
+  CASE lower(metric)
+    WHEN "cosine" THEN
+      @@myResult = 1 - inner_product(@@myList1, @@myList2) / (sqrt(inner_product(@@myList1, @@myList1)) * sqrt(inner_product(@@myList2, @@myList2)));
+    WHEN "euclidean" THEN
+      FOREACH i IN [0, @@myList1.size() - 1 ] DO
+        @@sqrSum += (@@myList1.get(i) - @@myList2.get(i)) * (@@myList1.get(i) - @@myList2.get(i));
+      END;
+      @@myResult = sqrt(@@sqrSum);
+    WHEN "ip" THEN
+      @@myResult = inner_product(@@myList1, @@myList2);
+    ELSE
+      RAISE invalid_metric_type ("Invalid metric algorithm provided, currently supported: cosine, euclidean and ip.");
+    END
+  ;
+
+  RETURN @@myResult;
+}

gds/vector/elements_sum.gsql

@@ -0,0 +1,41 @@
+CREATE FUNCTION gds.vector.elements_sum(list<double> list1) RETURNS(float) {
+
+  /*
+  First Author: Jue Yuan
+  First Commit Date:  Nov 27, 2024 
+
+  Recent Author: Jue Yuan
+  Recent Commit Date: Nov 27, 2024 
+
+  Maturity:
+      alpha
+
+  Description:
+      Calculates the sum of all elements in a vector, represented as a list of double values.
+      This function is useful for aggregating vector components in mathematical and statistical operations.
+
+  Parameters:
+      list<double> list1:
+          The input vector as a list of double values.
+
+  Returns:
+      float:
+          The sum of all elements in the input vector.
+
+  Logic Overview:
+      Iterates through each element in the input list.
+      Accumulates the sum of all elements.
+      Returns the final sum as a floating-point value.
+
+  Use Case:
+      This function is valuable in various data processing tasks, such as computing vector norms,
+      validating data integrity, or performing aggregations in machine learning and statistical analysis.
+  */
+
+  SumAccum<float> @@mySum;
+
+  FOREACH i IN list1 DO
+    @@mySum += i;
+  END;
+  RETURN @@mySum;
+}

gds/vector/euclidean_distance.gsql

@@ -0,0 +1,62 @@
+CREATE FUNCTION gds.vector.euclidean_distance(list<double> list1, list<double> list2) RETURNS(float) {
+
+  /*
+  First Author: Jue Yuan
+  First Commit Date:  Nov 27, 2024 
+
+  Recent Author: Jue Yuan
+  Recent Commit Date: Nov 27, 2024 
+
+  Maturity:
+      alpha
+
+  Description:
+      Calculates the Euclidean distance between two vectors represented as lists of double values.
+      Euclidean distance measures the straight-line distance between two points in multi-dimensional space,
+      making it a fundamental metric in various computational and analytical applications.
+
+  Parameters:
+      list<double> list1:
+          The first vector as a list of double values.
+      list<double> list2:
+          The second vector as a list of double values.
+
+  Returns:
+      float:
+          The Euclidean distance between the two input vectors.
+
+  Exceptions:
+      list_size_mismatch (90000): Raised when the input vectors are not of equal size.
+
+  Logic Overview:
+      Input Validation:
+          Ensures both vectors have the same length.
+      Distance Calculation:
+          Iterates through corresponding elements of both vectors.
+          Computes the sum of the squared differences between each pair of elements.
+          Returns the square root of the accumulated sum, representing the Euclidean distance.
+
+  Formula:
+      Distance = sqrt((x1 - y1)^2 + (x2 - y2)^2 + ... + (xn - yn)^2)
+      Where xi and yi are elements of list1 and list2, respectively.
+
+  Use Case:
+      This function is widely used in machine learning (e.g., k-nearest neighbors), data science,
+      and pattern recognition tasks to measure the similarity or dissimilarity between data points.
+  */
+
+  EXCEPTION list_size_mismatch (90000);
+  ListAccum<double> @@myList1 = list1;
+  ListAccum<double> @@myList2 = list2;
+
+  IF (@@myList1.size() != @@myList2.size()) THEN
+    RAISE list_size_mismatch ("Two lists provided for gds.vector.euclidean_distance have different sizes.");
+  END;
+
+  SumAccum<float> @@sqrSum;
+  FOREACH i IN [0, @@myList1.size() - 1 ] DO
+    @@sqrSum += (@@myList1.get(i) - @@myList2.get(i)) * (@@myList1.get(i) - @@myList2.get(i));
+  END;
+
+  RETURN sqrt(@@sqrSum);
+}

gds/vector/ip_distance.gsql

@@ -0,0 +1,58 @@
+CREATE FUNCTION gds.vector.ip_distance(list<double> list1, list<double> list2) RETURNS(float) {
+
+  /*
+  First Author: Jue Yuan
+  First Commit Date:  Nov 27, 2024 
+
+  Recent Author: Jue Yuan
+  Recent Commit Date: Nov 27, 2024 
+
+  Maturity:
+      alpha
+
+  Description:
+      Calculates the inner product (dot product) between two vectors represented as lists of double values.
+      The inner product is a key measure in linear algebra, indicating the magnitude of the projection of one vector onto another.
+      This function provides a similarity measure commonly used in machine learning and data analysis.
+
+  Parameters:
+      list<double> list1:
+          The first vector as a list of double values.
+      list<double> list2:
+          The second vector as a list of double values.
+
+  Returns:
+      float:
+          The inner product (dot product) of the two input vectors.
+
+  Exceptions:
+      list_size_mismatch (90000):
+          Raised when the input vectors are not of equal size.
+
+  Logic Overview:
+      Input Validation:
+          Ensures both vectors have the same length.
+      Inner Product Calculation:
+          Computes the sum of the element-wise products of the two vectors.
+
+  Formula:
+      Inner Product = (x1 x y1) + (x2 x y2) + ... + (xn x yn)
+      Where xi and yi are elements of list1 and list2, respectively.
+
+  Use Case:
+      This function is widely used in:
+          Calculating similarity in machine learning models (e.g., recommendation systems).
+          Performing vector projections in linear algebra.
+          Evaluating similarity between embeddings in natural language processing (NLP).
+  */
+
+  EXCEPTION list_size_mismatch (90000);
+  ListAccum<double> @@myList1 = list1;
+  ListAccum<double> @@myList2 = list2;
+
+  IF (@@myList1.size() != @@myList2.size()) THEN
+    RAISE list_size_mismatch ("Two lists provided for gds.vector.euclidean_distance have different sizes.");
+  END;
+
+  RETURN inner_product(@@myList1, @@myList2);
+}