> ## Documentation Index
> Fetch the complete documentation index at: https://villagesql.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Extensão vsql_cube para MySQL

> A extensão vsql_cube adiciona ao MySQL um tipo de coluna cube para armazenar pontos e caixas em até 100 dimensões, com funções de contenção, sobreposição e distância.

Use o `vsql_cube` quando várias colunas numéricas pertencem ao mesmo conjunto e
você quer consultá-las como um único valor. Uma cadeia de condições AND pode
testar se uma linha cai dentro de um intervalo, mas não pode ordenar linhas por
distância. O tipo `cube` faz as duas coisas. Ele é um port da extensão `cube`
do PostgreSQL. A maioria dos nomes de função do PostgreSQL é mantida; os
construtores `cube()`, os operadores e as suas funções de apoio
(`cube_contained`, `cube_overlap`, `distance_taxicab`,
`distance_chebyshev`) se tornam as funções nomeadas abaixo.

| | |
| - | - |
| **Mantenedor** | VillageSQL |
| **Código-fonte e documentação completa** | [villagesql/vsql-cube](https://github.com/villagesql/vsql-cube) |
| **Licença** | GPL-2.0 |

## Instalar

O `vsql_cube.veb` já está no diretório `lib/veb/` do servidor se você instalou
o VillageSQL com o script de instalação, a imagem Docker ou um tarball de
release. Instale-o no servidor com uma única instrução:

```sql theme={null}
INSTALL EXTENSION vsql_cube;
```

Confirme que ele está lá:

```sql theme={null}
SELECT EXTENSION_NAME
FROM INFORMATION_SCHEMA.EXTENSIONS
WHERE EXTENSION_NAME = 'vsql_cube';
```

```
+----------------+
| EXTENSION_NAME |
+----------------+
| vsql_cube      |
+----------------+
```

Para compilá-lo você mesmo, siga as instruções de compilação no
[repositório](https://github.com/villagesql/vsql-cube).

## O que ela adiciona

### O tipo cube

Declare a coluna como `` `cube`(N) ``, onde `N` é o maior número de dimensões que um valor pode ter, de 1 a 100.
`cube` é uma palavra reservada do MySQL, então precisa de crases, e a contagem
de dimensões é obrigatória.

```sql theme={null}
CREATE TABLE sensors (
    id      INT PRIMARY KEY,
    name    VARCHAR(32),
    reading `cube`(3)
);
```

Escreva os valores como uma string de coordenadas. A coluna a interpreta:

```sql theme={null}
INSERT INTO sensors VALUES
    (1, 'north', '12.5,40.1,3.0'),
    (2, 'south', '48.0,12.7,9.5'),
    (3, 'east',  '30.2,25.0,6.1');
```

### Funções

| Função | Retorna | O que faz |
| - | - | - |
| `cube_point_nd(x, y, ...)` | `cube` | Constrói um ponto a partir das suas coordenadas |
| `cube_box_nd(lower..., upper...)` | `cube` | Constrói uma caixa a partir do canto inferior seguido do superior |
| `cube_point(x)`, `cube_box(x, y)` | `cube` | Constrói um ponto ou uma caixa unidimensional |
| `cube_from_string(s)`, `cube_to_string(c)` | `cube`, string | Converte entre texto e `cube` |
| `cube_dim(c)` | int | Número de dimensões |
| `cube_coord(c, n)` | real | Coordenada `n`, contando pelo canto inferior esquerdo e depois pelo superior direito. Fora do intervalo retorna NULL |
| `cube_ll_coord(c, n)`, `cube_ur_coord(c, n)` | real | Coordenada `n` do canto inferior esquerdo ou superior direito |
| `cube_is_point(c)` | int | 1 quando o valor é um ponto, 0 quando é uma caixa |
| `cube_contains(a, b)`, `cube_contained_by(a, b)` | int | Se um valor engloba o outro |
| `cube_overlaps(a, b)` | int | Se dois valores compartilham algum espaço |
| `cube_distance(a, b)` | real | Distância euclidiana |
| `cube_taxicab_distance(a, b)` | real | Distância de Manhattan |
| `cube_chebyshev_distance(a, b)` | real | Distância de Chebyshev |
| `cube_union(a, b)`, `cube_inter(a, b)` | `cube` | A menor caixa que contém ambos; a interseção deles |
| `cube_enlarge(c, r, n)` | `cube` | Amplia um valor em `r` nas primeiras `n` dimensões |
| `cube_subset(c, d1, d2, ...)` | `cube` | Um novo valor a partir das dimensões listadas, contando a partir de 1 |
| `cube_add_dim(c, lo, hi, ...)` | `cube` | Acrescenta uma dimensão por par lo/hi |
| `cube_agg(c)` | `cube` | Agregado: a caixa delimitadora de todos os valores do grupo |
| `cube_scalar_agg(x)` | `cube` | Agregado: o intervalo delimitador de uma coluna numérica |

## Exemplo

Encontre os dois sensores mais próximos de uma leitura alvo e, depois, os sensores dentro de uma região:

```sql theme={null}
SELECT name, ROUND(cube_distance(reading, cube_point_nd(30, 25, 6)), 2) AS dist
FROM sensors
ORDER BY dist
LIMIT 2;
```

```
+-------+-------+
| name  | dist  |
+-------+-------+
| east  |  0.22 |
| south | 22.08 |
+-------+-------+
```

```sql theme={null}
SELECT name FROM sensors
WHERE cube_contains(cube_box_nd(10, 10, 0, 35, 45, 7), reading) = 1;
```

```
+-------+
| name  |
+-------+
| north |
| east  |
+-------+
```

> [!NOTE]
>
> Um argumento `cube` obtém a sua contagem de dimensões de uma coluna, então
> uma chamada funciona quando um dos seus argumentos `cube` é um valor de
> coluna ou o resultado de uma função que preserva a contagem de dimensões de
> uma coluna, como `cube_union` ou `cube_enlarge`. Uma chamada sem nenhum
> argumento desse tipo, como em `cube_dim(cube_point_nd(1, 2))`, falha com
> `ERROR 3219 (HY000): Cannot initialize function 'cube_dim': cannot determine
>     type parameters for vsql_cube.cube in argument 1`. Pelo mesmo motivo, insira
> uma string de coordenadas simples em vez de envolvê-la em `cube_point_nd()`.
>
> Cada argumento de coordenada de `cube_point_nd`, `cube_box_nd`, `cube_subset` e
> `cube_add_dim` também pode ser uma string separada por vírgulas, e as listas
> são unidas de ponta a ponta. Assim, `cube_point_nd('1,2,3')` e
> `cube_point_nd(1, 2, 3)` constroem o mesmo ponto.
> Passe uma string quando as coordenadas estão em uma coluna, que é o único
> caso que argumentos separados não conseguem expressar.

## Veja também

* [Consultas de intervalo multidimensionais no MySQL](https://villagesql.com/docs/en/guides/cube-queries.md) — um passo a passo mais longo de consultas de contenção, distância e vizinho mais próximo
* [Instalar extensões](https://villagesql.com/docs/pt-BR/extensions/install.md) — como o `INSTALL EXTENSION` funciona e onde o servidor procura um bundle
* [Extensões disponíveis](https://villagesql.com/docs/pt-BR/extensions/catalog) — o catálogo completo
* [villagesql/vsql-cube](https://github.com/villagesql/vsql-cube) — código-fonte, instruções de compilação e a referência completa de funções


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.