# Selecionar itens

> Escolha um item ou um subconjunto de uma lista por posição, intervalo, sorteio, regra ou nome. O nó é gratuito e envia a escolha e o resto a duas saídas.

Source: https://nodaro.ai/pt-BR/docs/nodes/automate/selector

O nó **Selecionar itens** (Selector) escolhe um item, ou vários itens, de uma lista. Você escolhe como selecionar: por posição, por intervalo, aleatoriamente, por uma regra sobre um campo ou por nome. O Selecionar itens envia os itens escolhidos para a saída **Selecionados** e todos os outros itens para a saída **Restantes**. Ele é executado na hora, não chama nenhum modelo e não custa créditos.

- Found in: Automate › Lists & Batching
- Output: text
- API type: `selector`

## Quando usar
- A mesma escolha alimenta vários nós. Um Selecionar itens substitui a mesma configuração em várias conexões.
- Você quer um item aleatório de uma lista e quer repetir a mesma escolha depois, com uma seed.
- Você quer o item cujo campo tem um valor específico, como o personagem chamado `hero`, ou todos os itens com pontuação de 15 ou mais.
- Você quer enviar os itens que não escolheu para outro lugar, pela saída **Restantes**.
- Você quer percorrer uma lista curta em ciclo com um número vindo de outro nó.

## Início rápido
### Adicionar o nó
Pressione Tab no canvas e escolha **Automatizar › Listas e lotes › Selecionar itens**.

### Conectar uma lista
Conecte uma lista à entrada **Lista**, por exemplo de um nó [**Lista** (List)](https://nodaro.ai/docs/nodes/automate/list), [**Dividir texto** (Split Text)](https://nodaro.ai/docs/nodes/automate/split-text), [**Filtrar lista** (Filter List)](https://nodaro.ai/docs/nodes/automate/filter-list) ou [**Extrair campo** (Extract Field)](https://nodaro.ai/docs/nodes/automate/extract-field) com a saída definida como lista.

### Escolher um modo
Abra o painel de configurações, escolha um **Modo** e preencha os campos dele. Os modos estão descritos abaixo.

### Conectar as saídas e executar
Conecte **Selecionados** ao próximo nó e **Restantes** a outro ramo, se você precisar dos outros itens. Depois de uma execução, o painel mostra as contagens em **Última execução**, como “Selecionados: 2 · Restantes: 3”.

Workflow: O Selecionar itens sorteia três prompts aleatórios de uma lista de dez, e o Gerar imagem é executado uma vez para cada prompt escolhido.

- Lista → Selecionar itens (lista)
- Selecionar itens → Gerar imagem (selecionados · Cada item)

## Entradas e saídas
| Entrada ou saída | Aceita ou envia | O que faz |
| --- | --- | --- |
| **Lista** | Listas de itens de texto, imagens, vídeos, áudio ou JSON | A lista de onde escolher. Quando vários nós estão conectados, as listas deles são juntadas na ordem em que você os conectou. |
| **Selecionados** | Uma lista | Os itens que o modo escolheu, na ordem original da lista. Um modo que escolhe um item envia uma lista com um item. |
| **Restantes** | Uma lista | Todos os itens que não foram escolhidos, na ordem original. |

Juntas, **Selecionados** e **Restantes** sempre cobrem todos os itens de entrada, e nenhum item fica nas duas. O Selecionar itens divide pela posição, não pelo valor, então os itens duplicados caem no lado certo. Por exemplo, com `a, b, a, c` e um intervalo de 2 a 3, **Selecionados** é `b, a` e **Restantes** é `a, c`.

## Modos
| Modo | Campos | Escolhe | Exemplo |
| --- | --- | --- | --- |
| **Item (índice único)** | **Índice** | 1 item | Em `a, b, c, d`, o índice `last-1` escolhe `c`. |
| **Intervalo (de/até/passo)** | **De**, **Até**, **Passo** | Vários itens | Em `a, b, c, d, e`, de `2` até `4` escolhe `b, c, d`. |
| **Lista (expressão com vírgulas)** | **Expressão** | Vários itens | Em `a, b, c, d, e`, a expressão `1, 3, 5` escolhe `a, c, e`. |
| **Aleatório (com seed)** | **Seed (opcional)**, **Quantidade** | O número de itens definido em **Quantidade** | Em `a, b, c, d`, uma seed de `42` e uma quantidade de 2 sempre escolhem os mesmos dois itens. |
| **Módulo (ciclo por índice)** | **Divisor** | 1 item | Em `a, b, c`, um divisor de `5` escolhe `c`. |
| **Predicado (filtro)** | **Campo**, **Operador**, **Valor**, **Correspondência**, **Diferenciar maiúsculas de minúsculas** | 1 item ou todas as correspondências | Em itens com um campo `score`, `score` maior ou igual a `15`, com **Correspondência** definida como **Todos**, escolhe todos os itens com pontuação de 15 ou mais. |
| **Chave nomeada (busca)** | **Campo**, **Valor** | 0 ou 1 item | Em personagens com um campo `name`, `name` = `hero` escolhe o herói. |

### Item
O **Índice** conta a partir de 1. Escreva um número como `3`, ou conte a partir do fim com `last` e `last-1`, `last-2` e assim por diante. Um índice além do fim da lista usa o item válido mais próximo. Um índice que não pode ser lido usa o primeiro item.

### Intervalo
**De** e **Até** são ambos incluídos e contam a partir de 1. Um **Passo** negativo anda para trás, de um **De** maior até um **Até** menor. Os itens escolhidos continuam na ordem original da lista: em `a, b, c, d`, de `last` até `1` com passo `-2` escolhe `b, d`. Um passo de `0` conta como `1`. Um intervalo que avança com passo negativo, ou que recua com passo positivo, não escolhe nada.

### Lista
A **Expressão** mistura posições únicas e intervalos, separados por vírgulas, por exemplo `1, 3..5, last`. Os itens escolhidos ficam na ordem original da lista, seja qual for a ordem em que você os escreve, e uma posição escrita duas vezes é escolhida uma vez só. Outros exemplos: `1..5`, `1..10:2` para um item a cada dois e `1..last-1` para todos os itens, menos o último. Uma parte que não pode ser lida faz o nó escolher todos os itens.

### Aleatório
A **Quantidade** é o número de itens a sortear, e o padrão é 1. Cada item é sorteado no máximo uma vez, e uma quantidade maior que a lista escolhe a lista inteira. Com uma **Seed**, a mesma seed e a mesma lista sempre geram a mesma escolha. Sem seed, cada execução sorteia de novo.

### Módulo
O módulo escolhe um item dividindo o **Divisor** pelo tamanho da lista. O resto é a posição, contada a partir de 0. Por exemplo, um divisor de `5` em uma lista de 3 itens deixa resto 2, que é o terceiro item. Use-o para percorrer uma lista curta em ciclo com um número que muda, vindo de outro nó. Um divisor que não é um número usa o primeiro item.

### Predicado
O predicado mantém os itens cujo **Campo** passa em um teste. Deixe o **Campo** vazio para testar o item inteiro. O **Operador** é um destes: **é igual a**, **é diferente de**, **maior que**, **menor que**, **maior ou igual**, **menor ou igual**, **contém**, **não contém**, **começa com**, **termina com**, **corresponde à regex**, **existe** e **não existe**. Com **Correspondência** definida como **Primeiro**, o Selecionar itens escolhe só a primeira correspondência; com **Todos**, escolhe todas as correspondências. Uma regra que não corresponde a nada envia todos os itens para **Restantes**.

### Chave nomeada
A chave nomeada é a forma curta do predicado para uma busca por nome: ela escolhe o primeiro item cujo **Campo** é igual ao **Valor**. Quando nada corresponde, **Selecionados** fica vazio e todos os itens vão para **Restantes**.

## Usar um valor de outro nó
Quatro campos aceitam o rótulo de outro nó entre chaves, como `{CharacterName}`. Quando o Selecionar itens é executado, as chaves são substituídas pelo valor desse nó.

| Campo | Modo | Uso típico |
| --- | --- | --- |
| **Divisor** | Módulo | Percorrer uma lista em ciclo com um número vindo de outro nó. |
| **Valor** | Predicado | Comparar cada item com a saída de outro nó. |
| **Valor** | Chave nomeada | Buscar o item cujo nome vem de outro nó, como `{CharacterName}`. |
| **Seed** | Aleatório | Fazer a escolha aleatória depender de outro nó, como `{Project}`. |

Todos os outros campos são lidos exatamente como foram digitados. Leia mais em [Variáveis de prompt](https://nodaro.ai/docs/concepts/prompt-variables).

## Quando uma configuração está errada
O Selecionar itens nunca interrompe um workflow por causa de uma configuração. Cada problema tem um resultado seguro:

| Caso | Resultado |
| --- | --- |
| Nenhuma lista conectada, ou uma lista vazia | **Selecionados** e **Restantes** ficam vazios. O nó termina sem erro. |
| Um índice que não pode ser lido | O primeiro item. |
| Um índice além do fim | O item válido mais próximo. |
| Um divisor que não é um número | O primeiro item. |
| Uma quantidade maior que a lista | A lista inteira. |
| Um predicado ou uma chave nomeada que não corresponde a nada | **Selecionados** fica vazio, e **Restantes** tem todos os itens. |

O nó só falha em um erro inesperado e, nesse caso, mostra a mensagem de erro.

## Selecionar itens ou uma configuração de conexão
Toda conexão também pode escolher itens com o modo **Item**, ou com as abas de intervalo e de lista dos modos **Cada item** e **Conjunto**. Os dois contam as posições do mesmo jeito. Em uma conexão, os itens mantêm a ordem em que você os escolhe: de `last` até `1` com passo `-1` inverte a lista, e uma posição escrita duas vezes é passada duas vezes.

| Use uma configuração de conexão quando | Use o nó Selecionar itens quando |
| --- | --- |
| Um só próximo nó precisa de uma escolha simples por posição, intervalo ou lista | A mesma escolha alimenta vários próximos nós |
| Você quer a escolha oculta no canvas | A escolha é importante o bastante para aparecer como um nó com rótulo |
| Item, intervalo ou lista é tudo de que você precisa | Você precisa dos modos aleatório, módulo, predicado ou chave nomeada |
| Uma saída basta | Você quer os outros itens em **Restantes** |

Leia [Listas e lotes](https://nodaro.ai/docs/concepts/lists-and-batching) para ver todos os modos de conexão.

## Créditos
O Selecionar itens é gratuito em todas as edições.

## Dicas
- **Execute o próximo nó por escolha.** **Selecionados** sempre envia uma lista. Mude a conexão que sai de **Selecionados** para **Cada item** para executar o próximo nó uma vez por item escolhido.
- **Confira as contagens.** A **Última execução** mostra quantos itens foram para **Selecionados** e para **Restantes**, que é o jeito mais rápido de testar uma regra.
- **Filtre muitos, escolha um.** Para manter todos os itens que atendem a várias condições, use o [Filtrar lista](https://nodaro.ai/docs/nodes/automate/filter-list). Para escolher um item ou uma fatia, use o Selecionar itens.

## Frequently asked questions

### Qual é a diferença entre o nó “Selecionar itens” e o modo “Item” de uma conexão?

As escolhas por item, intervalo e lista de uma conexão são escolhas rápidas para um único próximo nó e ficam invisíveis no canvas. O nó “Selecionar itens” mostra a escolha como um nó com rótulo e pode alimentar vários nós. Ele também envia os itens não escolhidos para a saída “Restantes” e acrescenta os modos “Aleatório”, “Módulo”, “Predicado” e “Chave nomeada”.

### Uma escolha aleatória pode ser repetida exatamente?

Sim. Informe uma “Seed”, e a mesma seed com a mesma lista sempre gera a mesma escolha. Deixe a “Seed” vazia para ter uma nova escolha aleatória a cada execução.

### O que acontece quando uma configuração do “Selecionar itens” está errada?

O workflow continua sendo executado. Um índice inválido usa o primeiro item. Um índice além do fim usa o item mais próximo, e uma regra que não corresponde a nada envia todos os itens para “Restantes”.

### O nó “Selecionar itens” custa créditos?

Não. O “Selecionar itens” é gratuito em todas as edições. Ele é executado na hora e nunca chama um modelo.

### Como executo o próximo nó uma vez para cada item escolhido?

Mude a conexão que sai de “Selecionados” para “Cada item”. O próximo nó é então executado uma vez por item escolhido.