Hologres:roaringbitmap

Fonctionnement

Un bitmap Roaring divise les entiers 32 bits en blocs de 2^16. Les entiers d'un même bloc partagent les 16 bits de poids fort ; les 16 bits de poids faible sont stockés dans un conteneur. Un tableau dynamique sert d'index primaire pour ces conteneurs.

Deux types de conteneurs optimisent le stockage et les performances :

Cette structure permet une récupération rapide des valeurs et des opérations binaires efficaces (AND, OR, XOR) entre les conteneurs.

Limites

• Seules les instances exclusives Hologres V0.10 et ultérieures prennent en charge les fonctions Roaring Bitmap.

  Vérifiez la version de votre instance dans la console Hologres. Si la version est antérieure à la V0.10, mettez l'instance à niveau dans la console ou rejoignez le groupe DingTalk pour obtenir une assistance technique. Consultez les rubriques Common upgrade preparation failure errors et Obtain online support for Hologres .

• Les fonctions Roaring Bitmap sont chargées par défaut dans le schéma public et ne peuvent être installées que dans ce schéma.

• À partir de Hologres V3.1, le type de données RoaringBitmap64 est pris en charge. Certaines fonctions Roaring Bitmap peuvent traiter des données de type RoaringBitmap64. Cependant, lors du traitement de données RoaringBitmap64, ces fonctions n'acceptent pas les paramètres d'entrée constants.

• Avant d'utiliser les fonctions Roaring Bitmap, activez l'extension avec l'instruction suivante. L'extension s'applique à une base de données spécifique : exécutez cette instruction une fois par base de données. Répétez l'opération pour chaque nouvelle base de données créée.

  -- Enable the extension.
  CREATE EXTENSION roaringbitmap;

  Pour supprimer l'extension :

  DROP EXTENSION roaringbitmap;

  Important

  Évitez d'utiliser DROP EXTENSION <extension_name> CASCADE;. L'option CASCADE supprime l'extension ainsi que toutes ses données et tous les objets dépendants, y compris les données PostGIS, les données Roaring Bitmap, les données Proxima, les données de journaux binaires (binary log) et les données BSI, ainsi que les métadonnées, tables, vues et objets serveur dépendants.

• Les colonnes Roaring Bitmap ne peuvent pas servir d'index bitmap ou dictionary.

• Lors de la création d'une table contenant une colonne Roaring Bitmap, spécifiez explicitement le type de colonne comme roaringbitmap (32 bits) ou roaringbitmap64 (64 bits). Les calculs mixtes entre ces deux types ne sont pas pris en charge.

  -- Create a table with a 32-bit roaring bitmap column.
  CREATE TABLE t_rb_32 (
      bucket int,
      x roaringbitmap
  );
  
  -- Create a table with a 64-bit roaring bitmap column.
  CREATE TABLE t_rb_64 (
      bucket int,
      x roaringbitmap64
  );
  
  -- Mixed calculations return an error.
  -- ERROR: operator does not exist: roaringbitmap & roaringbitmap64
  SELECT
      a.x & b.x
  FROM
      t_rb_32 a
  JOIN t_rb_64 b ON a.bucket = b.bucket;

Opérateurs

Sauf indication contraire, tous les opérateurs ci-dessous prennent en charge les types RoaringBitmap et RoaringBitmap64.

Fonctions Roaring Bitmap

-- Prepare data.
CREATE TABLE public.tn (
    id INT,
    num BIGINT[]
);
INSERT INTO public.tn ("id", "num") VALUES (01, '{1,2}');

SELECT rb64_build(num) rb_num, num FROM public.tn;

rb_num                                                                          | num
--------------------------------------------------------------------------------+------
\x030100000000000000000000003a30000001000000000001001000000001000200             | {1,2}

-- Create a sample table.
CREATE TABLE rb_text (
    id int,
    a text
);

-- Insert data.
INSERT INTO rb_text
    VALUES (1, '\x3a300000010000000000090010000000010002000300040005000600070008000900c800');

-- Convert to RoaringBitmap and compute AND cardinality.
SELECT
    rb_and_cardinality_agg(roaringbitmap_in(a::cstring))
FROM
    rb_text;

 rb_and_cardinality_agg
------------------------
                     10

Fonctions d'agrégation Roaring Bitmap

-- OR aggregate: returns the union of all input bitmaps.
SELECT rb_or_agg(bitmap)
FROM (VALUES
    (rb_build('{1,2,3}')),
    (rb_build('{2,3,4}'))
) t(bitmap);
-- Result: {1,2,3,4}

-- AND aggregate: returns the intersection of all input bitmaps.
SELECT rb_and_agg(bitmap)
FROM (VALUES
    (rb_build('{1,2,3}')),
    (rb_build('{2,3,4}'))
) t(bitmap);
-- Result: {2,3}

-- OR cardinality aggregate.
SELECT rb_or_cardinality_agg(bitmap)
FROM (VALUES
    (rb_build('{1,2,3}')),
    (rb_build('{2,3,4}'))
) t(bitmap);
-- Result: 4

-- AND cardinality aggregate.
SELECT rb_and_cardinality_agg(bitmap)
FROM (VALUES
    (rb_build('{1,2,3}')),
    (rb_build('{2,3,4}'))
) t(bitmap);
-- Result: 2

-- XOR aggregate: returns elements in exactly one of the two bitmaps.
SELECT rb_xor_agg(bitmap)
FROM (VALUES
    (rb_build('{1,2,3}')),
    (rb_build('{2,3,4}'))
) t(bitmap);
-- Result: {1,4}

-- XOR cardinality aggregate.
SELECT rb_xor_cardinality_agg(bitmap)
FROM (VALUES
    (rb_build('{1,2,3}')),
    (rb_build('{2,3,4}'))
) t(bitmap);
-- Result: 2

Autres fonctions Roaring Bitmap

Les fonctions suivantes prennent uniquement en charge le type RoaringBitmap (32 bits).

Exemples

L'exemple complet suivant illustre un flux de travail de bout en bout : activation de l'extension, création d'une table, insertion de données, exécution d'opérations binaires et inspection des résultats.

1. Activez l'extension.

   CREATE EXTENSION roaringbitmap;

2. Créez une table pour stocker les données Roaring Bitmap.

   -- Create table t1.
   CREATE TABLE public.t1 (id integer, bitmap roaringbitmap);

3. Insérez des données Roaring Bitmap.

   -- Build a bitmap from an explicit array.
   INSERT INTO public.t1 SELECT 1, RB_BUILD(ARRAY[1,2,3,4,5,6,7,8,9,200]);
   
   -- Build a bitmap by aggregating a generated series.
   INSERT INTO public.t1 SELECT 2, RB_BUILD_AGG(e) FROM GENERATE_SERIES(1,100) e;

4. Exécutez des opérations binaires.

   -- OR the two bitmaps.
   SELECT RB_OR(a.bitmap, b.bitmap)
   FROM (SELECT bitmap FROM public.t1 WHERE id = 1) AS a,
        (SELECT bitmap FROM public.t1 WHERE id = 2) AS b;

   Sortie attendue (l'union de {1..9, 200} et {1..100}) :

    rb_or
   -------
    {1,2,3,4,5,6,7,8,9,10,...,100,200}

5. Exécutez des opérations d'agrégation pour combiner tous les bitmaps de la table.

   SELECT RB_OR_AGG(bitmap)  FROM public.t1;  -- union of all bitmaps
   SELECT RB_AND_AGG(bitmap) FROM public.t1;  -- intersection of all bitmaps
   SELECT RB_XOR_AGG(bitmap) FROM public.t1;  -- symmetric difference
   SELECT RB_BUILD_AGG(id)   FROM public.t1;  -- build a bitmap from the id column

6. Calculez la cardinalité (le nombre de bits définis).

   SELECT RB_CARDINALITY(bitmap) FROM public.t1;

   Sortie attendue :

    id | rb_cardinality
   ----+----------------
     1 |             10
     2 |            100

7. Listez tous les décalages définis.

   SELECT RB_ITERATE(bitmap) FROM public.t1 WHERE id = 1;

   Sortie attendue :

    rb_iterate
   ------------
             1
             2
             3
             4
             5
             6
             7
             8
             9
           200

8. Convertissez un bitmap Roaring en tableau.

   SELECT RB_TO_ARRAY(bitmap) FROM public.t1 WHERE id = 1;

   Sortie attendue :

              rb_to_array
   --------------------------------
    {1,2,3,4,5,6,7,8,9,200}