Passer au contenu principal
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;
┌─num─┐
│  60 │
└─────┘

SELECT groupNumericIndexedVectorState(UserID, PlayTime) as res, toTypeName(res), numericIndexedVectorAllValueSum(res) FROM t;
┌─res─┬─toTypeName(res)─────────────────────────────────────────────┬─numericIndexedVectorAllValueSum(res)──┐
│     │ AggregateFunction(groupNumericIndexedVector, UInt8, UInt8)  │ 60                                    │
└─────┴─────────────────────────────────────────────────────────────┴───────────────────────────────────────┘

SELECT groupNumericIndexedVectorStateIf(UserID, PlayTime, day = '2025-04-22') as res, toTypeName(res), numericIndexedVectorAllValueSum(res) FROM t;
┌─res─┬─toTypeName(res)────────────────────────────────────────────┬─numericIndexedVectorAllValueSum(res)──┐
│     │ AggregateFunction(groupNumericIndexedVector, UInt8, UInt8) │ 30                                    │
└─────┴────────────────────────────────────────────────────────────┴───────────────────────────────────────┘

SELECT groupNumericIndexedVectorStateIf('BSI', 32, 0)(UserID, PlayTime, day = '2025-04-22') as res, toTypeName(res), numericIndexedVectorAllValueSum(res) FROM t;
┌─res─┬─toTypeName(res)──────────────────────────────────────────────────────────┬─numericIndexedVectorAllValueSum(res)──┐
│     │ AggregateFunction('BSI', 32, 0)(groupNumericIndexedVector, UInt8, UInt8) │ 30                                    │
└─────┴──────────────────────────────────────────────────────────────────────────┴───────────────────────────────────────┘
La documentation ci-dessous est générée à partir de la table système system.functions.

​
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
Query
SELECT numericIndexedVectorAllValueSum(numericIndexedVectorBuild(mapFromArrays([1, 2, 3], [10, 20, 30]))) AS res;
Response
┌─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
Query
SELECT numericIndexedVectorBuild(mapFromArrays([1, 2, 3], [10, 20, 30])) AS res, toTypeName(res);
Response
┌─res─┬─toTypeName(res)────────────────────────────────────────────┐
│     │ 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
Query
SELECT numericIndexedVectorCardinality(numericIndexedVectorBuild(mapFromArrays([1, 2, 3], [10, 20, 30]))) AS res;
Response
┌─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
Query
SELECT numericIndexedVectorGetValue(numericIndexedVectorBuild(mapFromArrays([1, 2, 3], [10, 20, 30])), 3) AS res;
Response
┌─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
Query
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;
Response
┌─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
Query
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;
Response
┌─res1────────┬─res2────────────┐
│ {2:2,3:1.5} │ {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
Query
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;
Response
┌─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
Query
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;
Response
┌─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
Query
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;
Response
┌─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
Query
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;
Response
┌─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
Query
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;
Response
┌─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 de retour Renvoie un nouvel objet numericIndexedVector. Exemples
Query
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;
Response
┌─res1──────────┬─res2─────────────┐
│ {2:200,3:600} │ {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
Query
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;
Response
┌─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
Query
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;
Response
┌─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
Query
SELECT numericIndexedVectorShortDebugString(numericIndexedVectorBuild(mapFromArrays([1, 2, 3], [10, 20, 30]))) AS res\G;
Response
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
Query
SELECT numericIndexedVectorToMap(numericIndexedVectorBuild(mapFromArrays([1, 2, 3], [10, 20, 30]))) AS res;
Response
┌─res──────────────┐
│ {1:10,2:20,3:30} │
└──────────────────┘
Dernière modification le 25 juin 2026