# Pesquisa semântica para AWS Glue Data Catalog
<a name="catalog-semantic-search"></a>

**nota**  
O contexto de negócios e a pesquisa semântica estão em demonstração para o AWS Glue e estão sujeitos a alterações.

A pesquisa semântica permite descobrir ativos de dados por significado, além da correspondência exata de palavras-chave. Os resultados são classificados por semelhança semântica com sua consulta. Você pode restringir os resultados usando filtros por tipo de ativo, campos de metadados e termos do glossário.

## Uso da API SearchAssets
<a name="catalog-semantic-search-api"></a>

A API `SearchAssets` aceita `SearchText`, `FilterClause` ou ambas as opções. Quando nenhuma opção é fornecida, a API exibe todos os ativos. Parâmetros opcionais: `Sort`, `MaxResults`, `NextToken`.

### Busca de texto
<a name="catalog-semantic-search-text"></a>

```
aws glue search-assets \
    --search-text "customer purchases"
```

Resultado do exemplo:

```
{
    "Items": [
        {"Id": "c9vq7sh2fk4t2h", "AssetName": "Customer Sales Transactions", "AssetTypeId": "Table"}
    ]
}
```

Limite os resultados com `--max-results`:

```
aws glue search-assets \
    --search-text "quarterly revenue" \
    --max-results 5
```

### Filtrar os resultados de pesquisa
<a name="catalog-semantic-search-filters"></a>

Use `FilterClause` para restringir os resultados. Tipos de filtros compatíveis:
+ **AttributeFilter** – Operadores: `equals`, `greaterThan`, `greaterThanOrEquals`, `lessThan`, `lessThanOrEquals`, `notExists`.
+ **AndAllFilters** – Todos os filtros devem corresponder (AND lógico).
+ **OrAnyFilters** – Pelo menos um deve corresponder (OR lógico).

**Para filtrar por um único atributo**  
Filtrar somente os ativos da tabela:

```
aws glue search-assets \
    --search-text "revenue" \
    --filter-clause '{
        "AttributeFilter": {
            "Attribute": "type",
            "Operator": "equals",
            "Value": {"StringValue": "Table"}
        }
    }'
```

**Para combinar filtros com a lógica AND**  
Encontrar ativos da tabela atualizados após um registro de data e hora:

```
aws glue search-assets \
    --search-text "customer data" \
    --filter-clause '{
        "AndAllFilters": [
            {"AttributeFilter": {"Attribute": "type", "Operator": "equals", "Value": {"StringValue": "Table"}}},
            {"AttributeFilter": {"Attribute": "updatedAt", "Operator": "greaterThan", "Value": {"LongValue": 1718400000}}}
        ]
    }'
```

**Para combinar filtros com a lógica OR**  
Pesquisar tabelas ou ativos de habilidades:

```
aws glue search-assets \
    --search-text "customer data" \
    --filter-clause '{
        "OrAnyFilters": [
            {"AttributeFilter": {"Attribute": "type", "Operator": "equals", "Value": {"StringValue": "Table"}}},
            {"AttributeFilter": {"Attribute": "type", "Operator": "equals", "Value": {"StringValue": "Skill"}}}
        ]
    }'
```

**Para filtrar por termo do glossário**  
Filtrar ativos marcados com uma tag de um termo específico do glossário (por ID do termo):

```
aws glue search-assets \
    --search-text "financial data" \
    --filter-clause '{
        "AttributeFilter": {
            "Attribute": "glossaryTerms",
            "Operator": "equals",
            "Value": {"StringValue": "{{glossary-term-id}}"}
        }
    }'
```

**Para usar filtros AND e OR aninhados**  
Encontrar uma tabela ou ativos de habilidades com um termo específico do glossário:

```
aws glue search-assets \
    --search-text "customer" \
    --filter-clause '{
        "AndAllFilters": [
            {"OrAnyFilters": [
                {"AttributeFilter": {"Attribute": "type", "Operator": "equals", "Value": {"StringValue": "Table"}}},
                {"AttributeFilter": {"Attribute": "type", "Operator": "equals", "Value": {"StringValue": "Skill"}}}
            ]},
            {"AttributeFilter": {"Attribute": "glossaryTerms", "Operator": "equals", "Value": {"StringValue": "{{glossary-term-id}}"}}}
        ]
    }'
```

### Classificação dos resultados da pesquisa
<a name="catalog-semantic-search-sort"></a>

Por padrão, os resultados são classificados por relevância semântica. Para classificar por atributo:

```
aws glue search-assets \
    --search-text "customer purchases" \
    --sort '{"Attribute": "assetName", "Order": "ASCENDING"}'
```

```
aws glue search-assets \
    --search-text "customer purchases" \
    --sort '{"Attribute": "updatedAt", "Order": "DESCENDING"}'
```

**nota**  
Quando você especifica um atributo de classificação, os resultados são ordenados de acordo com esse atributo e não por relevância semântica.

### Paginação de resultados da pesquisa
<a name="catalog-semantic-search-pagination"></a>

Quando os resultados excedem `MaxResults`, a resposta inclui um `NextToken`. Use-o para recuperar páginas adicionais.

```
aws glue search-assets \
    --search-text "customer data" \
    --max-results 10 \
    --next-token "eyJsYXN0RXZhbHVhdGVkS2V5Ijp7ImlkIjp7InMiOiJhMWIyYzNkNCJ9fX0="
```

Continue até que a resposta não inclua mais um `NextToken`.

## Executar consultas somente com filtros
<a name="catalog-semantic-search-filter-only"></a>

Use somente `FilterClause` sem `SearchText` para listar os ativos sem classificação semântica.

```
aws glue search-assets \
    --filter-clause '{"AttributeFilter": {"Attribute": "type", "Operator": "equals", "Value": {"StringValue": "Table"}}}' \
    --max-results 20
```

**nota**  
Quando você omite `SearchText` e `FilterClause`, a API exibe todos os ativos.

## Exemplos
<a name="catalog-semantic-search-examples"></a>

**Para descobrir ativos de habilidades para um domínio**  
Encontrar os ativos de habilidades relacionados aos dados de vendas:

```
aws glue search-assets \
    --search-text "sales domain usage rules" \
    --filter-clause '{"AttributeFilter": {"Attribute": "type", "Operator": "equals", "Value": {"StringValue": "Skill"}}}'
```

**nota**  
Essa consulta exibe somente ativos de habilidades personalizados. As habilidades gerenciadas não são exibidas pela API `SearchAssets`.

**Para combinar a pesquisa e a classificação de textos**  
Obter uma visão abrangente dos ativos correspondentes:

```
aws glue search-assets \
    --search-text "customer" \
    --sort '{"Attribute": "updatedAt", "Order": "DESCENDING"}' \
    --max-results 10
```