Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Fonctions de NumericIndexedVector

View as MarkdownEdit this pageReport an issueSet up docs MCP

NumericIndexedVector est une structure de données abstraite qui encapsule un vecteur et implémente des opérations d’agrégation vectorielle ainsi que des opérations point par point. Bit-Sliced Index est sa méthode de stockage. Pour les fondements théoriques et les cas d’utilisation, consultez l’article Large-Scale Metric Computation in Online Controlled Experiment Platform.

BSI

Dans la méthode de stockage BSI (Bit-Sliced Index), les données sont stockées dans Bit-Sliced Index, puis compressées à l’aide de Roaring Bitmap. Les opérations d’agrégation et les opérations point par point s’effectuent directement sur les données compressées, ce qui peut améliorer considérablement l’efficacité du stockage et des requêtes.

Un vecteur contient des index et leurs valeurs correspondantes. Voici quelques caractéristiques et contraintes de cette structure de données en mode de stockage BSI :

  • Le type d’index peut être UInt8, UInt16 ou UInt32. Remarque : compte tenu des performances de l’implémentation 64 bits de Roaring Bitmap, le format BSI ne prend pas en charge UInt64/Int64.
  • Le type de valeur peut être Int8, Int16, Int32, Int64, UInt8, UInt16, UInt32, UInt64, Float32 ou Float64. Remarque : le type de valeur ne s’élargit pas automatiquement. Par exemple, si vous utilisez UInt8 comme type de valeur, toute somme dépassant la capacité de UInt8 entraînera un dépassement de capacité au lieu d’être promue vers un type supérieur ; de même, les opérations sur des entiers produiront des résultats entiers (par exemple, une division ne sera pas automatiquement convertie en résultat à virgule flottante). Il est donc important de planifier et de définir le type de valeur à l’avance. Dans des scénarios réels, les types à virgule flottante (Float32/Float64) sont couramment utilisés.
  • Seuls deux vecteurs ayant le même type d’index et le même type de valeur peuvent effectuer des opérations.
  • Le stockage sous-jacent utilise Bit-Sliced Index, les bitmaps servant à stocker les index. Roaring Bitmap est utilisé comme implémentation spécifique des bitmaps. Une bonne pratique consiste à concentrer autant que possible les index dans plusieurs conteneurs Roaring Bitmap afin de maximiser la compression et les performances des requêtes.
  • Le mécanisme Bit-Sliced Index convertit la valeur en binaire. Pour les types à virgule flottante, la conversion utilise une représentation en virgule fixe, ce qui peut entraîner une perte de précision. La précision peut être ajustée en personnalisant le nombre de bits utilisés pour la partie fractionnaire ; la valeur par défaut est de 24 bits, ce qui est suffisant pour la plupart des scénarios. Vous pouvez personnaliser le nombre de bits entiers et de bits fractionnaires lors de la construction de NumericIndexedVector à l’aide de la fonction d’agrégation groupNumericIndexedVector avec -State.
  • Il existe trois cas pour les index : valeur non nulle, valeur nulle et inexistante. Dans NumericIndexedVector, seules les valeurs non nulles et nulles sont stockées. De plus, dans les opérations point par point entre deux NumericIndexedVectors, la valeur d’un index inexistant est traitée comme 0. Dans le cas d’une division, le résultat est zéro lorsque le diviseur est zéro.

Créer un objet numericIndexedVector

Il existe deux façons de créer cette structure : la première consiste à utiliser la fonction d'agrégation groupNumericIndexedVector avec -State. Vous pouvez ajouter le suffixe -if pour prendre en charge une condition supplémentaire. La fonction d'agrégation ne traitera que les lignes qui satisfont à la condition. La seconde consiste à le construire à partir d'un map à l'aide de numericIndexedVectorBuild. La fonction groupNumericIndexedVectorState permet de personnaliser, via des paramètres, le nombre de bits de la partie entière et de la partie fractionnaire, contrairement à numericIndexedVectorBuild.

groupNumericIndexedVector

Construit un NumericIndexedVector à partir de deux colonnes de données et renvoie la somme de toutes les valeurs sous forme de type Float64. Si le suffixe State est ajouté, la fonction renvoie un objet NumericIndexedVector.

Syntaxe

groupNumericIndexedVectorState(col1, col2)
groupNumericIndexedVectorState(type, integer_bit_num, fraction_bit_num)(col1, col2)

Paramètres

  • type : String, facultatif. Spécifie le format de stockage. Actuellement, seul 'BSI' est pris en charge.
  • integer_bit_num : UInt32, facultatif. Applicable avec le format de stockage 'BSI', ce paramètre indique le nombre de bits utilisés pour la partie entière. Lorsque le type d’index est un type entier, la valeur par défaut correspond au nombre de bits utilisés pour stocker l’index. Par exemple, si le type d’index est UInt16, la valeur par défaut de integer_bit_num est 16. Pour les types d’index Float32 et Float64, la valeur par défaut de integer_bit_num est 40, de sorte que la partie entière des données représentables se situe dans l’intervalle [-2^39, 2^39 - 1]. L’intervalle autorisé est [0, 64].
  • fraction_bit_num : UInt32, facultatif. Applicable avec le format de stockage 'BSI', ce paramètre indique le nombre de bits utilisés pour la partie fractionnaire. Lorsque le type de valeur est un entier, la valeur par défaut est 0 ; lorsqu’il est de type Float32 ou Float64, la valeur par défaut est 24. L’intervalle valide est [0, 24].
  • Il existe également une contrainte selon laquelle l’intervalle valide de integer_bit_num + fraction_bit_num est [0, 64].
  • col1 : La colonne d’index. Types pris en charge : UInt8/UInt16/UInt32/Int8/Int16/Int32.
  • col2 : La colonne de valeur. Types pris en charge : Int8/Int16/Int32/Int64/UInt8/UInt16/UInt32/UInt64/Float32/Float64.

Valeur de retour

Une valeur Float64 représentant la somme de toutes les valeurs.

Exemple

Données de test :

UserID  PlayTime
1       10
2       20
3       30

Requête & résultat :

SELECT groupNumericIndexedVector(UserID, PlayTime) AS num FROM t;
┌

numericIndexedVectorAllValueSum

Introduit dans : v25.7.0

Renvoie la somme de toutes les valeurs du numericIndexedVector.

Syntaxe

numericIndexedVectorAllValueSum(v)

Arguments

Valeur renvoyée

Renvoie la somme. Float64

Exemples

Exemple d’utilisation

SELECT numericIndexedVectorAllValueSum(numericIndexedVectorBuild(mapFromArrays([1, 2, 3], [10, 20, 30]))) AS res;
┌─res─┐
│  60 │
└─────┘

numericIndexedVectorBuild

Introduit dans : v25.7.0

Crée un NumericIndexedVector à partir d’une map. Les clés de la map représentent les index du vecteur, et les valeurs de la map représentent les valeurs du vecteur.

Syntaxe

numericIndexedVectorBuild(map)

Arguments

  • map — Une correspondance entre l’index et la valeur. Map

Valeur renvoyée

Renvoie un objet NumericIndexedVector. AggregateFunction

Exemples

Exemple d’utilisation

-- A NumericIndexedVector is a binary value, so it is shown with `hex`.
SELECT
    hex(numericIndexedVectorBuild(mapFromArrays([1, 2, 3], [10, 20, 30]))) AS res,
    toTypeName(numericIndexedVectorBuild(mapFromArrays([1, 2, 3], [10, 20, 30]))) AS type;
┌─res────────────────────────────────────────────────────────────────┬─type───────────────────────────────────────────────────────┐
│ 080000000000000001010000020103000002020300000201030000020203010101 │ AggregateFunction(groupNumericIndexedVector, UInt8, UInt8) │
└────────────────────────────────────────────────────────────────────┴────────────────────────────────────────────────────────────┘

numericIndexedVectorCardinality

Introduit dans : v25.7.0

Renvoie la cardinalité (nombre d’index uniques) du numericIndexedVector.

Syntaxe

numericIndexedVectorCardinality(v)

Arguments

Valeur renvoyée

Renvoie le nombre d’index distincts. UInt64

Exemples

Exemple d’utilisation

SELECT numericIndexedVectorCardinality(numericIndexedVectorBuild(mapFromArrays([1, 2, 3], [10, 20, 30]))) AS res;
┌─res─┐
│   3 │
└─────┘

numericIndexedVectorGetValue

Introduit dans : v25.7.0

Récupère la valeur correspondant à un index donné dans un numericIndexedVector.

Syntaxe

numericIndexedVectorGetValue(v, i)

Arguments

Valeur renvoyée

Une valeur numérique du même type que les valeurs de NumericIndexedVector. (U)Int* ou Float*

Exemples

Exemple d'utilisation

SELECT numericIndexedVectorGetValue(numericIndexedVectorBuild(mapFromArrays([1, 2, 3], [10, 20, 30])), 3) AS res;
┌─res─┐
│  30 │
└─────┘

numericIndexedVectorPointwiseAdd

Introduit dans : v25.7.0

Effectue une addition point par point entre un numericIndexedVector et soit un autre numericIndexedVector, soit une constante numérique.

Syntaxe

numericIndexedVectorPointwiseAdd(v1, v2)

Arguments

Valeur renvoyée

Renvoie un nouvel objet numericIndexedVector.

Exemples

Exemple d'utilisation

WITH
    numericIndexedVectorBuild(mapFromArrays([1, 2, 3], arrayMap(x -> toInt32(x), [10, 20, 30]))) AS vec1,
    numericIndexedVectorBuild(mapFromArrays([2, 3, 4], arrayMap(x -> toInt32(x), [10, 20, 30]))) AS vec2
SELECT
    numericIndexedVectorToMap(numericIndexedVectorPointwiseAdd(vec1, vec2)) AS res1,
    numericIndexedVectorToMap(numericIndexedVectorPointwiseAdd(vec1, 2)) AS res2;
┌─res1──────────────────┬─res2─────────────┐
│ {1:10,2:30,3:50,4:30} │ {1:12,2:22,3:32} │
└───────────────────────┴──────────────────┘

numericIndexedVectorPointwiseDivide

Introduit dans : v25.7.0

Effectue une division point par point entre un numericIndexedVector et soit un autre numericIndexedVector, soit une constante numérique.

Syntaxe

numericIndexedVectorPointwiseDivide(v1, v2)

Arguments

Valeur renvoyée

Renvoie un nouvel objet numericIndexedVector.

Exemples

Exemple d'utilisation

with
    numericIndexedVectorBuild(mapFromArrays([1, 2, 3], arrayMap(x -> toFloat64(x), [10, 20, 30]))) as vec1,
    numericIndexedVectorBuild(mapFromArrays([2, 3, 4], arrayMap(x -> toFloat64(x), [10, 20, 30]))) as vec2
SELECT
    numericIndexedVectorToMap(numericIndexedVectorPointwiseDivide(vec1, vec2)) AS res1,
    numericIndexedVectorToMap(numericIndexedVectorPointwiseDivide(vec1, 2)) AS res2;
┌─res1────────────────┬─res2────────────┐
│ {1:0,2:2,3:1.5,4:0} │ {1:5,2:10,3:15} │
└─────────────────────┴─────────────────┘

numericIndexedVectorPointwiseEqual

Introduit dans : v25.7.0

Effectue une comparaison point par point entre un numericIndexedVector et soit un autre numericIndexedVector, soit une constante numérique. Le résultat est un numericIndexedVector contenant les indices pour lesquels les valeurs sont égales, toutes les valeurs correspondantes étant définies sur 1.

Syntaxe

numericIndexedVectorPointwiseEqual(v1, v2)

Arguments

Valeur renvoyée

Renvoie un nouvel objet numericIndexedVector.

Exemples

with
    numericIndexedVectorBuild(mapFromArrays([1, 2, 3], arrayMap(x -> toFloat64(x), [10, 20, 30]))) as vec1,
    numericIndexedVectorBuild(mapFromArrays([2, 3, 4], arrayMap(x -> toFloat64(x), [20, 20, 30]))) as vec2
SELECT
    numericIndexedVectorToMap(numericIndexedVectorPointwiseEqual(vec1, vec2)) AS res1,
    numericIndexedVectorToMap(numericIndexedVectorPointwiseEqual(vec1, 20)) AS res2;
┌─res1──┬─res2──┐
│ {2:1} │ {2:1} │
└───────┴───────┘

numericIndexedVectorPointwiseGreater

Introduit dans : v25.7.0

Effectue une comparaison point par point entre un numericIndexedVector et soit un autre numericIndexedVector, soit une constante numérique. Le résultat est un numericIndexedVector contenant les indices pour lesquels la valeur du premier vecteur est supérieure à celle du second, toutes les valeurs correspondantes étant fixées à 1.

Syntaxe

numericIndexedVectorPointwiseGreater(v1, v2)

Arguments

Valeur renvoyée

Renvoie un nouvel objet numericIndexedVector. numericIndexedVector

Exemples

Exemple d’utilisation

with
    numericIndexedVectorBuild(mapFromArrays([1, 2, 3], arrayMap(x -> toFloat64(x), [10, 20, 50]))) as vec1,
    numericIndexedVectorBuild(mapFromArrays([2, 3, 4], arrayMap(x -> toFloat64(x), [20, 40, 30]))) as vec2
SELECT
    numericIndexedVectorToMap(numericIndexedVectorPointwiseGreater(vec1, vec2)) AS res1,
    numericIndexedVectorToMap(numericIndexedVectorPointwiseGreater(vec1, 20)) AS res2;
┌─res1──────┬─res2──┐
│ {1:1,3:1} │ {3:1} │
└───────────┴───────┘

numericIndexedVectorPointwiseGreaterEqual

Introduit dans : v25.7.0

Effectue une comparaison point par point entre un numericIndexedVector et soit un autre numericIndexedVector, soit une constante numérique. Le résultat est un numericIndexedVector contenant les indices pour lesquels la valeur du premier vecteur est supérieure ou égale à celle du second, toutes les valeurs correspondantes étant définies à 1.

Syntaxe

numericIndexedVectorPointwiseGreaterEqual(v1, v2)

Arguments

Valeur renvoyée

Renvoie un nouvel objet numericIndexedVector.

Exemples

Exemple d'utilisation

with
    numericIndexedVectorBuild(mapFromArrays([1, 2, 3], arrayMap(x -> toFloat64(x), [10, 20, 50]))) as vec1,
    numericIndexedVectorBuild(mapFromArrays([2, 3, 4], arrayMap(x -> toFloat64(x), [20, 40, 30]))) as vec2
SELECT
    numericIndexedVectorToMap(numericIndexedVectorPointwiseGreaterEqual(vec1, vec2)) AS res1,
    numericIndexedVectorToMap(numericIndexedVectorPointwiseGreaterEqual(vec1, 20)) AS res2;
┌─res1──────────┬─res2──────┐
│ {1:1,2:1,3:1} │ {2:1,3:1} │
└───────────────┴───────────┘

numericIndexedVectorPointwiseLess

Introduit dans : v25.7.0

Effectue une comparaison point par point entre un numericIndexedVector et soit un autre numericIndexedVector, soit une constante numérique. Le résultat est un numericIndexedVector contenant les indices pour lesquels la valeur du premier vecteur est inférieure à celle du second, toutes les valeurs correspondantes étant définies sur 1.

Syntaxe

numericIndexedVectorPointwiseLess(v1, v2)

Arguments

Valeur renvoyée

Renvoie un nouvel objet numericIndexedVector. numericIndexedVector

Exemples

Exemple d'utilisation

with
    numericIndexedVectorBuild(mapFromArrays([1, 2, 3], arrayMap(x -> toFloat64(x), [10, 20, 30]))) as vec1,
    numericIndexedVectorBuild(mapFromArrays([2, 3, 4], arrayMap(x -> toFloat64(x), [20, 40, 30]))) as vec2
SELECT
    numericIndexedVectorToMap(numericIndexedVectorPointwiseLess(vec1, vec2)) AS res1,
    numericIndexedVectorToMap(numericIndexedVectorPointwiseLess(vec1, 20)) AS res2;
┌─res1──────┬─res2──┐
│ {3:1,4:1} │ {1:1} │
└───────────┴───────┘

numericIndexedVectorPointwiseLessEqual

Introduit dans : v25.7.0

Effectue une comparaison point par point entre un numericIndexedVector et un autre numericIndexedVector ou une constante numérique. Le résultat est un numericIndexedVector contenant les indices pour lesquels la valeur du premier vecteur est inférieure ou égale à celle du second, toutes les valeurs correspondantes étant définies à 1.

Syntaxe

numericIndexedVectorPointwiseLessEqual(v1, v2)

Arguments

Valeur renvoyée

Renvoie un nouvel objet numericIndexedVector. numericIndexedVector

Exemples

Exemple d'utilisation

with
    numericIndexedVectorBuild(mapFromArrays([1, 2, 3], arrayMap(x -> toFloat64(x), [10, 20, 30]))) as vec1,
    numericIndexedVectorBuild(mapFromArrays([2, 3, 4], arrayMap(x -> toFloat64(x), [20, 40, 30]))) as vec2
SELECT
    numericIndexedVectorToMap(numericIndexedVectorPointwiseLessEqual(vec1, vec2)) AS res1,
    numericIndexedVectorToMap(numericIndexedVectorPointwiseLessEqual(vec1, 20)) AS res2;
┌─res1──────────┬─res2──────┐
│ {2:1,3:1,4:1} │ {1:1,2:1} │
└───────────────┴───────────┘

numericIndexedVectorPointwiseMultiply

Introduit dans : v25.7.0

Effectue une multiplication point par point entre un numericIndexedVector et un autre numericIndexedVector ou une constante numérique.

Syntaxe

numericIndexedVectorPointwiseMultiply(v1, v2)

Arguments

valeur renvoyée

Renvoie un nouvel objet numericIndexedVector.

Exemples

with
    numericIndexedVectorBuild(mapFromArrays([1, 2, 3], arrayMap(x -> toInt32(x), [10, 20, 30]))) as vec1,
    numericIndexedVectorBuild(mapFromArrays([2, 3, 4], arrayMap(x -> toInt32(x), [10, 20, 30]))) as vec2
SELECT
    numericIndexedVectorToMap(numericIndexedVectorPointwiseMultiply(vec1, vec2)) AS res1,
    numericIndexedVectorToMap(numericIndexedVectorPointwiseMultiply(vec1, 2)) AS res2;
┌─res1──────────────────┬─res2─────────────┐
│ {1:0,2:200,3:600,4:0} │ {1:20,2:40,3:60} │
└───────────────────────┴──────────────────┘

numericIndexedVectorPointwiseNotEqual

Introduit dans : v25.7.0

Effectue une comparaison point par point entre un numericIndexedVector et un autre numericIndexedVector ou une constante numérique. Le résultat est un numericIndexedVector contenant les indices pour lesquels les valeurs sont différentes, toutes les valeurs correspondantes étant définies sur 1.

Syntaxe

numericIndexedVectorPointwiseNotEqual(v1, v2)

Arguments

Valeur renvoyée

Renvoie un nouvel objet numericIndexedVector. numericIndexedVector

Exemples

Exemple d'utilisation

with
    numericIndexedVectorBuild(mapFromArrays([1, 2, 3], arrayMap(x -> toFloat64(x), [10, 20, 30]))) as vec1,
    numericIndexedVectorBuild(mapFromArrays([2, 3, 4], arrayMap(x -> toFloat64(x), [20, 20, 30]))) as vec2
SELECT
    numericIndexedVectorToMap(numericIndexedVectorPointwiseNotEqual(vec1, vec2)) AS res1,
    numericIndexedVectorToMap(numericIndexedVectorPointwiseNotEqual(vec1, 20)) AS res2;
┌─res1──────────┬─res2──────┐
│ {1:1,3:1,4:1} │ {1:1,3:1} │
└───────────────┴───────────┘

numericIndexedVectorPointwiseSubtract

Introduit dans : v25.7.0

Effectue une soustraction point par point entre un numericIndexedVector et un autre numericIndexedVector ou une constante numérique.

Syntaxe

numericIndexedVectorPointwiseSubtract(v1, v2)

Arguments

Valeur renvoyée

Renvoie un nouvel objet numericIndexedVector. numericIndexedVector

Exemples

Exemple d'utilisation

WITH
    numericIndexedVectorBuild(mapFromArrays([1, 2, 3], arrayMap(x -> toInt32(x), [10, 20, 30]))) AS vec1,
    numericIndexedVectorBuild(mapFromArrays([2, 3, 4], arrayMap(x -> toInt32(x), [10, 20, 30]))) AS vec2
SELECT
    numericIndexedVectorToMap(numericIndexedVectorPointwiseSubtract(vec1, vec2)) AS res1,
    numericIndexedVectorToMap(numericIndexedVectorPointwiseSubtract(vec1, 2)) AS res2;
┌─res1───────────────────┬─res2────────────┐
│ {1:10,2:10,3:10,4:-30} │ {1:8,2:18,3:28} │
└────────────────────────┴─────────────────┘

numericIndexedVectorShortDebugString

Introduit dans : v25.7.0

Renvoie des informations internes du numericIndexedVector au format JSON. Cette fonction est principalement utilisée à des fins de débogage.

Syntaxe

numericIndexedVectorShortDebugString(v)

Arguments

Valeur renvoyée

Renvoie une chaîne JSON contenant des informations de débogage. String

Exemples

Exemple d'utilisation

SELECT numericIndexedVectorShortDebugString(numericIndexedVectorBuild(mapFromArrays([1, 2, 3], [10, 20, 30]))) AS res FORMAT Vertical;
Row 1:
──────
res: {"vector_type":"BSI","index_type":"char8_t","value_type":"char8_t","integer_bit_num":8,"fraction_bit_num":0,"zero_indexes_info":{"cardinality":0},"non_zero_indexes_info":{"total_cardinality":3,"all_value_sum":60,"number_of_bitmaps":8,"bitmap_info":{"cardinality":{"0":0,"1":2,"2":2,"3":2,"4":2,"5":0,"6":0,"7":0}}}}

numericIndexedVectorToMap

Introduit dans : v25.7.0

Convertit un numericIndexedVector en une map.

Syntaxe

numericIndexedVectorToMap(v)

Arguments

Valeur renvoyée

Renvoie une Map contenant des paires index-valeur.

Exemples

Exemple d'utilisation

SELECT numericIndexedVectorToMap(numericIndexedVectorBuild(mapFromArrays([1, 2, 3], [10, 20, 30]))) AS res;
┌─res──────────────┐
│ {1:10,2:20,3:30} │
└──────────────────┘
Navigation