Parâmetros em funções de roaring bitmap e como usar funções de roaring bitmap no Hologres - Hologres: Central de Documentação do Alibaba Cloud

Funcionamento

Um roaring bitmap divide inteiros de 32 bits em blocos de 2^16. Inteiros no mesmo bloco compartilham os 16 bits mais significativos; os 16 bits menos significativos ficam armazenados em um contêiner. Os contêineres residem em um array dinâmico que atua como índice primário.

Dois tipos de contêiner equilibram armazenamento e desempenho:

Tipo de contêiner	Uso	Capacidade
Contêiner de array	Blocos esparsos	Até 4.096 inteiros
Contêiner de bitmap	Blocos densos	Mais de 4.096 inteiros

Essa estrutura permite recuperação rápida de valores e operações bitwise eficientes (AND, OR, XOR) entre contêineres.

Limites

Somente instâncias exclusivas do Hologres V0.10 ou posterior oferecem suporte a funções de roaring bitmap.

Verifique a versão da sua instância no console do Hologres. Se a versão for anterior à V0.10, atualize a instância pelo console ou entre no grupo do DingTalk para obter suporte técnico. Consulte Erros comuns de falha na preparação de atualização e Obter suporte online para o Hologres .
As funções de roaring bitmap são carregadas no schema public por padrão e só podem ser carregadas nesse schema.
A partir do Hologres V3.1, há suporte ao tipo de dados RoaringBitmap64. Algumas funções de roaring bitmap processam dados do tipo RoaringBitmap64. Ao processar dados RoaringBitmap64, essas funções não aceitam parâmetros de entrada constantes.
Antes de usar funções de roaring bitmap, ative a extensão com a instrução abaixo. A extensão tem escopo de banco de dados — execute este comando uma vez por banco de dados. Repita o processo para cada novo banco de dados criado.
```
-- Enable the extension.
CREATE EXTENSION roaringbitmap;
```
Para remover a extensão:
```
DROP EXTENSION roaringbitmap;
```
Importante
Evite DROP EXTENSION <extension_name> CASCADE;. A opção CASCADE remove a extensão junto com todos os seus dados e objetos dependentes, incluindo dados do PostGIS, dados de roaring bitmap, dados do Proxima, dados de binary log, dados BSI, além de metadados, tabelas, visualizações e objetos de servidor dependentes.
Não é possível definir colunas de roaring bitmap como índices de bitmap ou dicionário.

Ao criar uma tabela com coluna de roaring bitmap, especifique explicitamente o tipo da coluna como roaringbitmap (32 bits) ou roaringbitmap64 (64 bits). Não há suporte para cálculos mistos entre os dois 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

Salvo indicação contrária, todos os operadores abaixo oferecem suporte aos tipos RoaringBitmap e RoaringBitmap64.

Operador	Tipo de entrada	Tipo de saída	Descrição	Exemplo	Resultado
`&`	RoaringBitmap	RoaringBitmap64, RoaringBitmap	RoaringBitmap64	Igual à entrada	AND	`rb_build('{1,2,3}') & rb_build('{3,4,5}')`	`{3}`
`	`	RoaringBitmap	RoaringBitmap64, RoaringBitmap	RoaringBitmap64	Igual à entrada	OR	`rb_build('{1,2,3}')	rb_build('{3,4,5}')`	`{1,2,3,4,5}`
`	`	RoaringBitmap	RoaringBitmap64, INTEGER	RoaringBitmap	RoaringBitmap64	OR (bitmap, inteiro); V1.3.16+	`rb_build('{1,2,3}')	6`	`{1,2,3,6}`
`	`	INTEGER, RoaringBitmap	RoaringBitmap64	RoaringBitmap	RoaringBitmap64	OR (inteiro, bitmap); V1.3.16+	`6	rb_build('{1,2,3}')`	`{1,2,3,6}`
`#`	RoaringBitmap	RoaringBitmap64, RoaringBitmap	RoaringBitmap64	Igual à entrada	XOR	`rb_build('{1,2,3}') # rb_build('{3,4,5}')`	`{1,2,4,5}`
`<<`	RoaringBitmap	RoaringBitmap64, BIGINT	RoaringBitmap	RoaringBitmap64	Deslocamento à esquerda; V1.3.16+	`rb_build('{1,2,3}') << 2`	`{3,4,5}`
`>>`	RoaringBitmap	RoaringBitmap64, BIGINT	RoaringBitmap	RoaringBitmap64	Deslocamento à direita; V1.3.16+	`rb_build('{1,2,3}') >> 3`	—
`-`	RoaringBitmap	RoaringBitmap64, RoaringBitmap	RoaringBitmap64	Igual à entrada	ANDNOT (bitmap, bitmap); V1.3.16+	`rb_build('{1,2,3}') - rb_build('{3,4,5}')`	`{1,2}`
`-`	RoaringBitmap	RoaringBitmap64, INTEGER	RoaringBitmap	RoaringBitmap64	ANDNOT (bitmap, inteiro)	`rb_build('{1,2,3}') - 3`	`{1,2}`
`@>`	RoaringBitmap	RoaringBitmap64, RoaringBitmap	RoaringBitmap64	BOOLEAN	A contém B	`rb_build('{1,2,3}') @> rb_build('{3,4,5}')`	`false`
`@>`	RoaringBitmap	RoaringBitmap64, INTEGER	BOOLEAN	A contém inteiro	`rb_build('{1,2,3}') @> 3`	`true`
`<@`	RoaringBitmap	RoaringBitmap64, RoaringBitmap	RoaringBitmap64	BOOLEAN	A está contido em B	`rb_build('{1,2,3}') <@ rb_build('{3,4,5}')`	`false`
`<@`	INTEGER, RoaringBitmap	RoaringBitmap64	BOOLEAN	Inteiro está contido em A	`3 <@ rb_build('{1,2,3}')`	`true`
`&&`	RoaringBitmap	RoaringBitmap64, RoaringBitmap	RoaringBitmap64	BOOLEAN	A intercepta B	`rb_build('{1,2,3}') && rb_build('{3,4,5}')`	`true`
`=`	RoaringBitmap	RoaringBitmap64, RoaringBitmap	RoaringBitmap64	BOOLEAN	Igualdade	`rb_build('{1,2,3}') = rb_build('{3,4,5}')`	`false`
`<>`	RoaringBitmap	RoaringBitmap64, RoaringBitmap	RoaringBitmap64	BOOLEAN	Diferença	`rb_build('{1,2,3}') <> rb_build('{3,4,5}')`	`true`

Funções de roaring bitmap

Funções compatíveis com RoaringBitmap e RoaringBitmap64

Função	Tipo de entrada	Tipo de saída	Descrição	Exemplo	Resultado
`rb_build_agg`	INTEGER	BIGINT	RoaringBitmap	RoaringBitmap64	Agrega offsets em um roaring bitmap. Entrada BIGINT (retornando RoaringBitmap64) requer V3.1+.	`rb_build_agg(1)`	`{1}`
`rb_cardinality`	RoaringBitmap	RoaringBitmap64	INTEGER	Retorna o número de elementos em um roaring bitmap.	`rb_cardinality(rb_build('{1,2,3,4,5}'))`	`5`
`rb_and_cardinality`	RoaringBitmap	RoaringBitmap64, RoaringBitmap	RoaringBitmap64	INTEGER	Retorna a cardinalidade da operação AND entre dois roaring bitmaps.	`rb_and_cardinality(rb_build('{1,2,3}'), rb_build('{3,4,5}'))`	`1`
`rb_or_cardinality`	RoaringBitmap	RoaringBitmap64, RoaringBitmap	RoaringBitmap64	INTEGER	Retorna a cardinalidade da operação OR entre dois roaring bitmaps.	`rb_or_cardinality(rb_build('{1,2,3}'), rb_build('{3,4,5}'))`	`5`
`rb_range`	RoaringBitmap	RoaringBitmap64, BIGINT, BIGINT	RoaringBitmap	RoaringBitmap64	Retorna elementos no intervalo [start, end), onde start é baseado em 1. Requer V1.3.16+.	`rb_range(rb_build('{1,2,3}'), 2, 3)`	—
`rb_minimum`	RoaringBitmap	RoaringBitmap64	INTEGER	Retorna o menor offset. Retorna -1 se o bitmap estiver vazio.	`rb_minimum(rb_build('{1,2,3}'))`	`1`
`rb_maximum`	RoaringBitmap	RoaringBitmap64	INTEGER	Retorna o maior offset. Retorna 0 se o bitmap estiver vazio.	`rb_maximum(rb_build('{1,2,3}'))`	`3`
`rb_to_array`	RoaringBitmap	RoaringBitmap64	INTEGER[]	Converte um roaring bitmap em um array de inteiros.	`rb_to_array(rb_build('{1,2,3}'))`	`{1,2,3}`
`rb_to_array_string`	RoaringBitmap	RoaringBitmap64, TEXT	TEXT	Converte um roaring bitmap em string, unindo os elementos com o delimitador especificado.	`rb_to_array_string(rb_build('{1,2,3}'), ',')`	`1,2,3`

Funções compatíveis apenas com RoaringBitmap64

Função	Tipo de entrada	Tipo de saída	Descrição	Exemplo	Resultado
`rb64_build`	BIGINT[]	RoaringBitmap64	Cria um roaring bitmap de 64 bits a partir de um array BIGINT. Requer V3.1+.	Confira o exemplo abaixo.	—

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

Saída esperada:

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

Funções compatíveis apenas com RoaringBitmap (32 bits)

Função	Tipo de entrada	Tipo de saída	Descrição	Exemplo	Resultado
`rb_build`	INTEGER[]	RoaringBitmap	Cria um roaring bitmap de 32 bits a partir de um array de inteiros.	`rb_build('{1,2,3,4,5}')`	`{1,2,3,4,5}`
`roaringbitmap_in`	TEXT	RoaringBitmap	Converte um roaring bitmap codificado em TEXT para o tipo RoaringBitmap. Requer V2.1.33+.	Confira o exemplo abaixo.	—
`rb_index`	RoaringBitmap, INTEGER	BIGINT	Retorna o índice baseado em 0 de um elemento. Retorna -1 se o elemento não existir. Requer V1.3.16+.	`rb_index(rb_build('{1,2,3}'), 3)`	`2`
`rb_and_null2empty`	RoaringBitmap, RoaringBitmap	RoaringBitmap	Operação AND; trata entradas NULL como bitmaps vazios. Requer V1.1.42+.	`rb_and_null2empty(rb_build(null), rb_build('{3,4,5}'))`	`{}`
`rb_or_null2empty`	RoaringBitmap, RoaringBitmap	RoaringBitmap	Operação OR; trata entradas NULL como bitmaps vazios. Requer V1.1.42+.	`rb_or_null2empty(rb_build(null), rb_build('{3,4,5}'))`	`{3,4,5}`
`rb_andnot_null2empty`	RoaringBitmap, RoaringBitmap	RoaringBitmap	Operação ANDNOT; trata entradas NULL como bitmaps vazios. Requer V1.1.42+.	`rb_andnot_null2empty(rb_build(null), rb_build('{3,4,5}'))`	`{}`
`rb_and_null2empty_cardinality`	RoaringBitmap, RoaringBitmap	INTEGER	Retorna a cardinalidade da operação AND; trata entradas NULL como bitmaps vazios. Requer V1.1.42+.	`rb_and_null2empty_cardinality(rb_build(null), rb_build('{3,4,5}'))`	`0`
`rb_or_null2empty_cardinality`	RoaringBitmap, RoaringBitmap	INTEGER	Retorna a cardinalidade da operação OR; trata entradas NULL como bitmaps vazios. Requer V1.1.42+.	`rb_or_null2empty_cardinality(rb_build(null), rb_build('{3,4,5}'))`	`3`
`rb_xor_cardinality`	RoaringBitmap, RoaringBitmap	INTEGER	Retorna a cardinalidade da operação XOR entre dois roaring bitmaps.	`rb_xor_cardinality(rb_build('{1,2,3}'), rb_build('{3,4,5}'))`	`4`
`rb_andnot_cardinality`	RoaringBitmap, RoaringBitmap	INTEGER	Retorna a cardinalidade da operação ANDNOT entre dois roaring bitmaps.	`rb_andnot_cardinality(rb_build('{1,2,3}'), rb_build('{3,4,5}'))`	`2`
`rb_andnot_null2empty_cardinality`	RoaringBitmap, RoaringBitmap	INTEGER	Retorna a cardinalidade da operação ANDNOT; trata entradas NULL como bitmaps vazios. Requer V1.1.42+.	`rb_andnot_null2empty_cardinality(rb_build(null), rb_build('{3,4,5}'))`	`0`
`rb_is_empty`	RoaringBitmap	BOOLEAN	Verifica se um roaring bitmap está vazio.	`rb_is_empty(rb_build('{1,2,3,4,5}'))`	`false`
`rb_fill`	RoaringBitmap, BIGINT, BIGINT	RoaringBitmap	Preenche offsets no intervalo [start, end), excluindo o limite final. Requer V1.3.16+.	`rb_fill(rb_build('{1,2,3}'), 5, 7)`	`{1,2,3,5,6}`
`rb_clear`	RoaringBitmap, BIGINT, BIGINT	RoaringBitmap	Limpa offsets no intervalo [start, end), excluindo o limite final. Requer V1.3.16+.	`rb_clear(rb_build('{1,2,3}'), 2, 3)`	—
`rb_contains_bitmap`	RoaringBitmap, RoaringBitmap	BOOLEAN	Verifica se o primeiro bitmap contém todos os elementos do segundo.	`rb_contains_bitmap(rb_build('{1,2,3}'), rb_build('{3}'))`	`true`
`rb_flip`	RoaringBitmap, INTEGER, INTEGER	RoaringBitmap	Inverte os offsets no intervalo especificado.	`rb_flip(rb_build('{1,2,3}'), 2, 3)`	—
`rb_range_cardinality`	RoaringBitmap, BIGINT, BIGINT	BIGINT	Retorna a cardinalidade dos elementos no intervalo [start, end), onde start é baseado em 1. Requer V1.3.16+.	`rb_range_cardinality(rb_build('{1,2,3}'), 2, 3)`	—
`rb_rank`	RoaringBitmap, INTEGER	INTEGER	Retorna a quantidade de elementos menores ou iguais ao offset especificado.	`rb_rank(rb_build('{1,2,3}'), 3)`	`3`
`rb_jaccard_dist`	RoaringBitmap, RoaringBitmap	DOUBLE PRECISION	Retorna a distância de Jaccard ou o coeficiente de similaridade de Jaccard entre dois roaring bitmaps. Requer V1.3.16+.	`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	Retorna o subconjunto [bitset_offset, bitset_offset+bitset_limit) do intervalo [range_start, range_end).	`rb_select(rb_build('{1,2,3,4,5,6,7,8,9}'), 5, 2)`	—
`rb_iterate`	RoaringBitmap	Conjunto de INTEGER	Retorna cada offset de um roaring bitmap como uma linha.	`rb_iterate(rb_build('{1,2,3}'))`	`1`, `2`, `3`

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

Saída esperada:

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

Funções de agregação de roaring bitmap

Funções compatíveis com RoaringBitmap e RoaringBitmap64

Todos os exemplos abaixo utilizam entrada de múltiplas linhas para demonstrar como a agregação mescla vários bitmaps.

Função	Tipo de entrada	Tipo de saída	Descrição	Exemplo	Resultado
`rb_or_agg`	RoaringBitmap	RoaringBitmap64	Igual à entrada	Agregação OR em todas as linhas de entrada.	Confira o exemplo abaixo.	—
`rb_and_agg`	RoaringBitmap	RoaringBitmap64	Igual à entrada	Agregação AND em todas as linhas de entrada.	Confira o exemplo abaixo.	—
`rb_or_cardinality_agg`	RoaringBitmap	RoaringBitmap64	INTEGER	Retorna a cardinalidade da agregação OR.	Confira o exemplo abaixo.	—
`rb_and_cardinality_agg`	RoaringBitmap	RoaringBitmap64	INTEGER	Retorna a cardinalidade da agregação AND.	Confira o exemplo abaixo.	—

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

Funções compatíveis apenas com RoaringBitmap (32 bits)

Função	Tipo de entrada	Tipo de saída	Descrição	Exemplo	Resultado
`rb_xor_agg`	RoaringBitmap	RoaringBitmap	Agregação XOR em todas as linhas de entrada.	Confira o exemplo abaixo.	—
`rb_xor_cardinality_agg`	RoaringBitmap	INTEGER	Retorna a cardinalidade da agregação XOR.	Confira o exemplo abaixo.	—

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

Outras funções de roaring bitmap

As funções a seguir oferecem suporte apenas ao tipo RoaringBitmap (32 bits).

Função	Tipo de entrada	Tipo de saída	Descrição	Exemplo	Resultado
`roaringbitmap_text`	TEXT, BOOLEAN	RoaringBitmap	Desserializa dados binários de RoaringBitmap de TEXT para uma estrutura RoaringBitmap. O segundo parâmetro controla a verificação de formato — defina-o como `true` para evitar dados de bitmap inválidos.	`roaringbitmap_text(':0', true)`	—
`rb_to_text`	RoaringBitmap	TEXT	Converte uma estrutura RoaringBitmap para sua representação binária em TEXT.	`rb_to_text(rb_build('{1,2,3}'))`	`\x3a300000...`

Exemplos

O exemplo completo a seguir demonstra um fluxo de trabalho inteiro: ativar a extensão, criar uma tabela, inserir dados, executar operações bitwise e inspecionar os resultados.

Ative a extensão.
```
CREATE EXTENSION roaringbitmap;
```

Crie uma tabela para armazenar dados de roaring bitmap.

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

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

Execute operações bitwise.

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

Saída esperada (a união de {1..9, 200} e {1..100}):

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

Execute operações de agregação para combinar todos os bitmaps da tabela.

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 a cardinalidade (quantidade de bits definidos).

SELECT RB_CARDINALITY(bitmap) FROM public.t1;

Saída esperada:

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

Liste todos os offsets definidos.

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

Saída esperada:

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

Converta um roaring bitmap em um array.

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

Saída esperada:

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