# Índices

Ativar, usar e reconstruir índices de recursos.

## Índices

Os índices permitem buscar registros rapidamente pelo valor de um campo, sem percorrer o recurso inteiro. É a forma padrão de converter um slug de uma URL no UUID de um registro.

### Ativando índices

Acrescente ao `.meta` uma lista `index` com os nomes dos campos a indexar:

```json
{
  "fields": {
    "title": { "name": "Title", "type": "text", "required": true },
    "title_slug": { "name": "URL slug", "type": "slug", "source": "title" }
  },
  "index": ["title_slug"]
}
```

Cada vez que um registro é gravado (`data_create` / `data_update`), o índice é atualizado automaticamente.

### Como os índices são guardados

Para cada campo indexado, o Nimbly cria um arquivo vazio em:

```
ext/data/<resource>/.index/<field_name>/<md5(field_value)>/<record_uuid>
```

Por exemplo, um artigo com `title_slug = "my-article"` e `uuid = "abc123"` criaria:

```
ext/data/articles/.index/title_slug/1a79a4d60de6718e8e5b326e338ae533/abc123
```

O arquivo é vazio; a existência dele é a entrada do índice. Guardar em `.index/` mantém os índices separados dos arquivos de registro e garante que sejam ignorados naturalmente ao percorrer pastas (que ignoram itens começados com ponto).

### Com splitdir

Quando `splitdir: true` também está definido, as pastas de índice seguem a mesma divisão em dois níveis:

```
ext/data/<resource>/.index/<field_name>/<aa>/<bb>/<md5(value)>/<record_uuid>
```

A biblioteca de dados cuida disso de forma transparente: a mesma API, com ou sem `splitdir`.

### Buscando um registro pelo slug (padrão para route.inc)

```php
<?php

$parts = router_match(__FILE__);
if ($parts === false || count($parts) !== 1) return;

$slug = $parts[0];
load_library('data');
load_library('util');

$records = data_read_index('articles', 'title_slug', md5_uuid($slug));
if (empty($records)) return;

$record = reset($records);
set_variable_dot('record', $record);
router_accept();
```

`data_read_index($resource, $index_name, $index_uuid)` devolve um array associativo `uuid => record` com todos os registros que têm o valor indexado. Numa busca por slug, é sempre um registro.

### Reconstruindo índices

Se você acrescentar `index` ao `.meta` de um recurso existente, os registros existentes ainda não terão entradas de índice. Reconstrua-as com:

```bash
php core/cli/nimbly.php index:rebuild
# prompts: lists all indexed resources and asks you to choose

php core/cli/nimbly.php index:rebuild articles
# direct: reindexes the 'articles' resource immediately
```

O comando pode ser rodado várias vezes com segurança. `reindex` ainda existe como nome antigo, mas use `index:rebuild` em documentação e scripts novos.

## `index:rebuild`
Reconstrói as entradas de índice de um recurso indexado. Use depois de acrescentar `index` ao `.meta` de um recurso existente, ou depois de importar registros fora do fluxo normal da API.

```bash
php core/cli/nimbly.php index:rebuild             # interactive: lists indexed resources, prompts for choice
php core/cli/nimbly.php index:rebuild articles    # direct: reindex the 'articles' resource
```

O comando percorre todos os registros do recurso e cria os arquivos de índice que faltam. Pode ser rodado várias vezes com segurança; as entradas existentes ficam como estão.