Parameters in roaring bitmap functions and how to use roaring bitmap functions in Hologres - Hologres

Los roaring bitmaps son mapas de bits comprimidos de forma eficiente, compatibles con muchos lenguajes de programación y plataformas de big data. En Hologres, las funciones de roaring bitmap son ideales para cargas de trabajo con cardinalidad muy alta, como la deduplicación, el filtrado por etiquetas y la recopilación de series temporales.

Funcionamiento

Un roaring bitmap divide los enteros de 32 bits en fragmentos de 2^16. Los enteros que pertenecen al mismo fragmento comparten los 16 bits más significativos, mientras que los 16 bits menos significativos se almacenan en un contenedor. Estos contenedores se guardan en un arreglo dinámico que actúa como índice principal.

Existen dos tipos de contenedores que equilibran el almacenamiento y el rendimiento:

Tipo de contenedor	Uso	Capacidad
Array container	Fragmentos dispersos	Hasta 4,096 enteros
Bitmap container	Fragmentos densos	Más de 4,096 enteros

Esta estructura permite recuperar valores rápidamente y ejecutar operaciones bit a bit (AND, OR, XOR) entre contenedores de manera eficiente.

Límites

Solo las instancias exclusivas de Hologres V0.10 y versiones posteriores admiten las funciones de roaring bitmap.

Compruebe la versión de su instancia en la consola de Hologres. Si la versión es anterior a la V0.10, actualice la instancia desde la consola o únase al grupo de DingTalk para obtener soporte técnico. Consulte Common upgrade preparation failure errors y Obtain online support for Hologres .
Las funciones de roaring bitmap se cargan de forma predeterminada en el esquema public y solo pueden cargarse en dicho esquema.
A partir de Hologres V3.1, se admite el tipo de datos RoaringBitmap64. Algunas funciones de roaring bitmap procesan datos del tipo RoaringBitmap64. Al procesar datos RoaringBitmap64, estas funciones no admiten parámetros de entrada constantes.
Antes de usar las funciones de roaring bitmap, habilite la extensión con la siguiente instrucción. La extensión tiene alcance de base de datos, así que ejecute esta instrucción una vez por cada base de datos. Repita el proceso para cualquier base de datos nueva que cree.
```
-- Enable the extension.
CREATE EXTENSION roaringbitmap;
```
Para eliminar la extensión:
```
DROP EXTENSION roaringbitmap;
```
Importante
Evite DROP EXTENSION <extension_name> CASCADE;. La opción CASCADE elimina la extensión junto con todos sus datos y objetos dependientes. Esto incluye los datos de PostGIS, de roaring bitmap, de Proxima, de registro binario y de BSI, además de los metadatos, tablas, vistas y objetos de servidor dependientes.
Las columnas de roaring bitmap no se pueden especificar como índices de mapa de bits ni de diccionario.

Cuando cree una tabla con una columna de roaring bitmap, especifique explícitamente el tipo de columna como roaringbitmap (32 bits) o roaringbitmap64 (64 bits). No se admiten cálculos combinados entre ambos tipos.

-- 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;

Operadores

Todos los operadores que se muestran a continuación admiten los tipos RoaringBitmap y RoaringBitmap64, salvo que se indique lo contrario.

Operador	Tipo de entrada	Tipo de salida	Descripción	Ejemplo	Resultado
`&`	RoaringBitmap	RoaringBitmap64, RoaringBitmap	RoaringBitmap64	Igual que la entrada	AND	`rb_build('{1,2,3}') & rb_build('{3,4,5}')`	`{3}`
`	`	RoaringBitmap	RoaringBitmap64, RoaringBitmap	RoaringBitmap64	Igual que la entrada	OR	`rb_build('{1,2,3}')	rb_build('{3,4,5}')`	`{1,2,3,4,5}`
`	`	RoaringBitmap	RoaringBitmap64, INTEGER	RoaringBitmap	RoaringBitmap64	OR (mapa de bits, entero); V1.3.16+	`rb_build('{1,2,3}')	6`	`{1,2,3,6}`
`	`	INTEGER, RoaringBitmap	RoaringBitmap64	RoaringBitmap	RoaringBitmap64	OR (entero, mapa de bits); V1.3.16+	`6	rb_build('{1,2,3}')`	`{1,2,3,6}`
`#`	RoaringBitmap	RoaringBitmap64, RoaringBitmap	RoaringBitmap64	Igual que la entrada	XOR	`rb_build('{1,2,3}') # rb_build('{3,4,5}')`	`{1,2,4,5}`
`<<`	RoaringBitmap	RoaringBitmap64, BIGINT	RoaringBitmap	RoaringBitmap64	Desplazamiento a la izquierda; V1.3.16+	`rb_build('{1,2,3}') << 2`	`{3,4,5}`
`>>`	RoaringBitmap	RoaringBitmap64, BIGINT	RoaringBitmap	RoaringBitmap64	Desplazamiento a la derecha; V1.3.16+	`rb_build('{1,2,3}') >> 3`	—
`-`	RoaringBitmap	RoaringBitmap64, RoaringBitmap	RoaringBitmap64	Igual que la entrada	ANDNOT (mapa de bits, mapa de bits); V1.3.16+	`rb_build('{1,2,3}') - rb_build('{3,4,5}')`	`{1,2}`
`-`	RoaringBitmap	RoaringBitmap64, INTEGER	RoaringBitmap	RoaringBitmap64	ANDNOT (mapa de bits, entero)	`rb_build('{1,2,3}') - 3`	`{1,2}`
`@>`	RoaringBitmap	RoaringBitmap64, RoaringBitmap	RoaringBitmap64	BOOLEAN	A contiene a B	`rb_build('{1,2,3}') @> rb_build('{3,4,5}')`	`false`
`@>`	RoaringBitmap	RoaringBitmap64, INTEGER	BOOLEAN	A contiene al entero	`rb_build('{1,2,3}') @> 3`	`true`
`<@`	RoaringBitmap	RoaringBitmap64, RoaringBitmap	RoaringBitmap64	BOOLEAN	A está contenido en B	`rb_build('{1,2,3}') <@ rb_build('{3,4,5}')`	`false`
`<@`	INTEGER, RoaringBitmap	RoaringBitmap64	BOOLEAN	El entero está contenido en A	`3 <@ rb_build('{1,2,3}')`	`true`
`&&`	RoaringBitmap	RoaringBitmap64, RoaringBitmap	RoaringBitmap64	BOOLEAN	A intersecta con B	`rb_build('{1,2,3}') && rb_build('{3,4,5}')`	`true`
`=`	RoaringBitmap	RoaringBitmap64, RoaringBitmap	RoaringBitmap64	BOOLEAN	Igualdad	`rb_build('{1,2,3}') = rb_build('{3,4,5}')`	`false`
`<>`	RoaringBitmap	RoaringBitmap64, RoaringBitmap	RoaringBitmap64	BOOLEAN	Diferencia	`rb_build('{1,2,3}') <> rb_build('{3,4,5}')`	`true`

Funciones de roaring bitmap

Funciones compatibles con RoaringBitmap y RoaringBitmap64

Función	Tipo de entrada	Tipo de salida	Descripción	Ejemplo	Resultado
`rb_build_agg`	INTEGER	BIGINT	RoaringBitmap	RoaringBitmap64	Agrega desplazamientos en un roaring bitmap. Las entradas BIGINT (que devuelven RoaringBitmap64) requieren la versión V3.1 o posterior.	`rb_build_agg(1)`	`{1}`
`rb_cardinality`	RoaringBitmap	RoaringBitmap64	INTEGER	Devuelve la cantidad de elementos de un roaring bitmap.	`rb_cardinality(rb_build('{1,2,3,4,5}'))`	`5`
`rb_and_cardinality`	RoaringBitmap	RoaringBitmap64, RoaringBitmap	RoaringBitmap64	INTEGER	Devuelve la cardinalidad de la operación AND entre dos roaring bitmaps.	`rb_and_cardinality(rb_build('{1,2,3}'), rb_build('{3,4,5}'))`	`1`
`rb_or_cardinality`	RoaringBitmap	RoaringBitmap64, RoaringBitmap	RoaringBitmap64	INTEGER	Devuelve la cardinalidad de la operación OR entre dos roaring bitmaps.	`rb_or_cardinality(rb_build('{1,2,3}'), rb_build('{3,4,5}'))`	`5`
`rb_range`	RoaringBitmap	RoaringBitmap64, BIGINT, BIGINT	RoaringBitmap	RoaringBitmap64	Devuelve los elementos del rango [start, end), donde start comienza en 1. Requiere la versión V1.3.16 o posterior.	`rb_range(rb_build('{1,2,3}'), 2, 3)`	—
`rb_minimum`	RoaringBitmap	RoaringBitmap64	INTEGER	Devuelve el desplazamiento mínimo. Devuelve -1 si el mapa de bits está vacío.	`rb_minimum(rb_build('{1,2,3}'))`	`1`
`rb_maximum`	RoaringBitmap	RoaringBitmap64	INTEGER	Devuelve el desplazamiento máximo. Devuelve 0 si el mapa de bits está vacío.	`rb_maximum(rb_build('{1,2,3}'))`	`3`
`rb_to_array`	RoaringBitmap	RoaringBitmap64	INTEGER[]	Convierte un roaring bitmap en un arreglo de enteros.	`rb_to_array(rb_build('{1,2,3}'))`	`{1,2,3}`
`rb_to_array_string`	RoaringBitmap	RoaringBitmap64, TEXT	TEXT	Convierte un roaring bitmap en una cadena y une los elementos con el delimitador especificado.	`rb_to_array_string(rb_build('{1,2,3}'), ',')`	`1,2,3`

Funciones compatibles solo con RoaringBitmap64

Función	Tipo de entrada	Tipo de salida	Descripción	Ejemplo	Resultado
`rb64_build`	BIGINT[]	RoaringBitmap64	Crea un roaring bitmap de 64 bits a partir de un arreglo BIGINT. Requiere la versión V3.1 o posterior.	Consulte el ejemplo a continuación.	—

-- 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;

Salida esperada:

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

Funciones compatibles solo con RoaringBitmap (32 bits)

Función	Tipo de entrada	Tipo de salida	Descripción	Ejemplo	Resultado
`rb_build`	INTEGER[]	RoaringBitmap	Crea un roaring bitmap de 32 bits a partir de un arreglo de enteros.	`rb_build('{1,2,3,4,5}')`	`{1,2,3,4,5}`
`roaringbitmap_in`	TEXT	RoaringBitmap	Convierte un roaring bitmap codificado en texto al tipo RoaringBitmap. Requiere la versión V2.1.33 o posterior.	Consulte el ejemplo a continuación.	—
`rb_index`	RoaringBitmap, INTEGER	BIGINT	Devuelve el índice de un elemento comenzando desde cero. Devuelve -1 si el elemento no existe. Requiere la versión V1.3.16 o posterior.	`rb_index(rb_build('{1,2,3}'), 3)`	`2`
`rb_and_null2empty`	RoaringBitmap, RoaringBitmap	RoaringBitmap	Operación AND. Si una entrada es NULL, devuelve la otra; si una entrada es un mapa de bits vacío ({}), devuelve {}. Requiere la versión V1.1.42 o posterior.	`rb_and_null2empty(rb_build(null), rb_build('{3,4,5}'))`	`{}`
`rb_or_null2empty`	RoaringBitmap, RoaringBitmap	RoaringBitmap	Operación OR; trata las entradas NULL como mapas de bits vacíos. Requiere la versión V1.1.42 o posterior.	`rb_or_null2empty(rb_build(null), rb_build('{3,4,5}'))`	`{3,4,5}`
`rb_andnot_null2empty`	RoaringBitmap, RoaringBitmap	RoaringBitmap	Operación ANDNOT; trata las entradas NULL como mapas de bits vacíos. Requiere la versión V1.1.42 o posterior.	`rb_andnot_null2empty(rb_build(null), rb_build('{3,4,5}'))`	`{}`
`rb_and_null2empty_cardinality`	RoaringBitmap, RoaringBitmap	INTEGER	Devuelve la cardinalidad de la operación AND. Trata las entradas NULL como mapas de bits vacíos ({}). Requiere la versión V1.1.42 o posterior.	`rb_and_null2empty_cardinality(rb_build(null), rb_build('{3,4,5}'))`	`0`
`rb_or_null2empty_cardinality`	RoaringBitmap, RoaringBitmap	INTEGER	Devuelve la cardinalidad de la operación OR; trata las entradas NULL como mapas de bits vacíos. Requiere la versión V1.1.42 o posterior.	`rb_or_null2empty_cardinality(rb_build(null), rb_build('{3,4,5}'))`	`3`
`rb_xor_cardinality`	RoaringBitmap, RoaringBitmap	INTEGER	Devuelve la cardinalidad de la operación XOR entre dos roaring bitmaps.	`rb_xor_cardinality(rb_build('{1,2,3}'), rb_build('{3,4,5}'))`	`4`
`rb_andnot_cardinality`	RoaringBitmap, RoaringBitmap	INTEGER	Devuelve la cardinalidad de la operación ANDNOT entre dos roaring bitmaps.	`rb_andnot_cardinality(rb_build('{1,2,3}'), rb_build('{3,4,5}'))`	`2`
`rb_andnot_null2empty_cardinality`	RoaringBitmap, RoaringBitmap	INTEGER	Devuelve la cardinalidad de la operación ANDNOT; trata las entradas NULL como mapas de bits vacíos. Requiere la versión V1.1.42 o posterior.	`rb_andnot_null2empty_cardinality(rb_build(null), rb_build('{3,4,5}'))`	`0`
`rb_is_empty`	RoaringBitmap	BOOLEAN	Comprueba si un roaring bitmap está vacío.	`rb_is_empty(rb_build('{1,2,3,4,5}'))`	`false`
`rb_fill`	RoaringBitmap, BIGINT, BIGINT	RoaringBitmap	Llena los desplazamientos en el rango [start, end), sin incluir el extremo final. Requiere la versión V1.3.16 o posterior.	`rb_fill(rb_build('{1,2,3}'), 5, 7)`	`{1,2,3,5,6}`
`rb_clear`	RoaringBitmap, BIGINT, BIGINT	RoaringBitmap	Borra los desplazamientos en el rango [start, end), sin incluir el extremo final. Requiere la versión V1.3.16 o posterior.	`rb_clear(rb_build('{1,2,3}'), 2, 3)`	—
`rb_contains_bitmap`	RoaringBitmap, RoaringBitmap	BOOLEAN	Comprueba si el primer mapa de bits contiene todos los elementos del segundo.	`rb_contains_bitmap(rb_build('{1,2,3}'), rb_build('{3}'))`	`true`
`rb_flip`	RoaringBitmap, INTEGER, INTEGER	RoaringBitmap	Invierte los desplazamientos dentro del rango especificado.	`rb_flip(rb_build('{1,2,3}'), 2, 3)`	—
`rb_range_cardinality`	RoaringBitmap, BIGINT, BIGINT	BIGINT	Devuelve la cardinalidad de los elementos en el rango [start, end), donde start comienza en 1. Requiere la versión V1.3.16 o posterior.	`rb_range_cardinality(rb_build('{1,2,3}'), 2, 3)`	—
`rb_rank`	RoaringBitmap, INTEGER	INTEGER	Devuelve la cantidad de elementos menores o iguales al desplazamiento especificado.	`rb_rank(rb_build('{1,2,3}'), 3)`	`3`
`rb_jaccard_dist`	RoaringBitmap, RoaringBitmap	DOUBLE PRECISION	Devuelve la distancia de Jaccard o el coeficiente de similitud de Jaccard entre dos roaring bitmaps. Requiere la versión V1.3.16 o posterior.	`rb_jaccard_dist(rb_build('{1,2,3}'), rb_build('{3,4}'))`	`0.75`
`rb_select`	RoaringBitmap, bitset_limit BIGINT, bitset_offset BIGINT=0, reverse BOOLEAN=false, range_start BIGINT=-2147483648, range_end BIGINT=2147483647	RoaringBitmap	Devuelve el subconjunto [bitset_offset, bitset_offset+bitset_limit) del rango [range_start, range_end).	`rb_select(rb_build('{1,2,3,4,5,6,7,8,9}'), 5, 2)`	—
`rb_iterate`	RoaringBitmap	Set of INTEGER	Devuelve cada desplazamiento de un roaring bitmap como una fila.	`rb_iterate(rb_build('{1,2,3}'))`	`1`, `2`, `3`

Ejemplo de roaringbitmap_in:

-- 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;

Salida esperada:

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

Funciones de agregación de roaring bitmap

Funciones compatibles con RoaringBitmap y RoaringBitmap64

Todos los ejemplos siguientes usan entradas de varias filas para mostrar cómo la agregación combina varios mapas de bits.

Función	Tipo de entrada	Tipo de salida	Descripción	Ejemplo	Resultado
`rb_or_agg`	RoaringBitmap	RoaringBitmap64	Igual que la entrada	Agregación OR en todas las filas de entrada.	Consulte el ejemplo a continuación.	—
`rb_and_agg`	RoaringBitmap	RoaringBitmap64	Igual que la entrada	Agregación AND en todas las filas de entrada.	Consulte el ejemplo a continuación.	—
`rb_or_cardinality_agg`	RoaringBitmap	RoaringBitmap64	INTEGER	Devuelve la cardinalidad de la agregación OR.	Consulte el ejemplo a continuación.	—
`rb_and_cardinality_agg`	RoaringBitmap	RoaringBitmap64	INTEGER	Devuelve la cardinalidad de la agregación AND.	Consulte el ejemplo a continuación.	—

-- 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

Funciones compatibles solo con RoaringBitmap (32 bits)

Función	Tipo de entrada	Tipo de salida	Descripción	Ejemplo	Resultado
`rb_xor_agg`	RoaringBitmap	RoaringBitmap	Agregación XOR en todas las filas de entrada.	Consulte el ejemplo a continuación.	—
`rb_xor_cardinality_agg`	RoaringBitmap	INTEGER	Devuelve la cardinalidad de la agregación XOR.	Consulte el ejemplo a continuación.	—

-- 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

Otras funciones de roaring bitmap

A continuación se presentan las funciones que admiten únicamente el tipo RoaringBitmap (32 bits).

Función	Tipo de entrada	Tipo de salida	Descripción	Ejemplo	Resultado
`roaringbitmap_text`	TEXT, BOOLEAN	RoaringBitmap	Deserializa datos binarios de RoaringBitmap desde TEXT hacia una estructura RoaringBitmap. El segundo parámetro controla la verificación de formato; establézcalo en `true` para evitar datos de mapa de bits no válidos.	`roaringbitmap_text(':0', true)`	—
`rb_to_text`	RoaringBitmap	TEXT	Convierte una estructura RoaringBitmap a su representación binaria en texto.	`rb_to_text(rb_build('{1,2,3}'))`	`\x3a300000...`

Ejemplos

El siguiente ejemplo integral muestra un flujo de trabajo completo: habilitar la extensión, crear una tabla, insertar datos, ejecutar operaciones bit a bit e inspeccionar los resultados.

Habilite la extensión.
```
CREATE EXTENSION roaringbitmap;
```

Cree una tabla para almacenar datos de roaring bitmap.

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

Inserte datos de 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;

Ejecute operaciones bit a bit.

-- 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;

Salida esperada (la unión de {1..9, 200} y {1..100}):

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

Ejecute operaciones de agregación para combinar todos los mapas de bits de la tabla.

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

Calcule la cardinalidad (la cantidad de bits establecidos).

SELECT RB_CARDINALITY(bitmap) FROM public.t1;

Salida esperada:

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

Enumere todos los desplazamientos establecidos.

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

Salida esperada:

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

Convierta un roaring bitmap en un arreglo.

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

Salida esperada:

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