Indexação JSON

Os campos JSON fornecem uma maneira flexível de armazenar metadados estruturados no Milvus. Sem indexação, as consultas em campos JSON requerem varreduras de coleção completa, que se tornam lentas à medida que seu conjunto de dados cresce. A indexação JSON permite pesquisas rápidas criando índices dentro dos seus dados JSON.

A indexação JSON é ideal para:

• Esquemas estruturados com chaves consistentes e conhecidas

• Consultas de igualdade e intervalo em caminhos JSON específicos

• Cenários em que é necessário um controlo preciso sobre as chaves que são indexadas

• Aceleração eficiente do armazenamento de consultas direcionadas

Sintaxe de indexação JSON

Ao criar um índice JSON, você especifica:

• Caminho JSON: A localização exata dos dados que deseja indexar

• Tipo de conversão de dados: Como interpretar e armazenar os valores indexados

• Conversão de tipo opcional: Transforma os dados durante a indexação, se necessário

Aqui está a sintaxe para indexar um campo JSON:

# Prepare index params
index_params = MilvusClient.prepare_index_params()

index_params.add_index(
    field_name="<json_field_name>",  # Name of the JSON field
    index_type="AUTOINDEX",  # Must be AUTOINDEX or INVERTED
    index_name="<unique_index_name>",  # Index name
    params={
        "json_path": "<path_to_json_key>",  # Specific key to be indexed within JSON data
        "json_cast_type": "<data_type>",  # Data type to use when interpreting and indexing the value
        # "json_cast_function": "<cast_function>"  # Optional: convert key values into a target type at index time
    }
)

Parâmetro	Descrição	Valor / Exemplo
field_name	O nome do seu campo JSON no esquema de coleção.	"metadata"
index_type	Deve ser "AUTOINDEX" ou "INVERTED" para indexação JSON.	"AUTOINDEX"
index_name	Identificador único para este índice.	"category_index"
json_path	O caminho para a chave que pretende indexar no seu objeto JSON.	Chave de nível superior: 'metadata["category"]' Chave aninhada: 'metadata["supplier"]["contact"]["email"]' Todo o objeto JSON: "metadata" Sub-objeto: 'metadata["supplier"]'
json_cast_type	O tipo de dados a utilizar ao interpretar e indexar o valor. Deve corresponder ao tipo de dados real da chave. Para obter uma lista dos tipos de conversão disponíveis, consulte Tipos de conversão suportados abaixo.	"VARCHAR"
json_cast_function	(Opcional) Converte valores de chave originais para um tipo de destino no momento da indexação. Esta configuração só é necessária quando os valores-chave são armazenados num formato errado e pretende converter o tipo de dados durante a indexação. Para obter uma lista das funções de conversão disponíveis, consulte Funções de conversão suportadas abaixo.	"STRING_TO_DOUBLE"

Tipos de conversão suportados

O Milvus suporta os seguintes tipos de dados para conversão no momento da indexação. Estes tipos garantem que os seus dados são interpretados corretamente para uma filtragem eficiente.

Tipo de fundição	Descrição	Exemplo de valor JSON
BOOL / bool	Utilizado para indexar valores booleanos, permitindo consultas que filtram em condições de verdadeiro/falso.	true, false
DOUBLE / double	Utilizado para valores numéricos, incluindo números inteiros e de vírgula flutuante. Permite a filtragem com base em intervalos ou igualdade (por exemplo, >, <, ==).	42, 99.99
VARCHAR / varchar	Utilizado para indexar valores de cadeia de caracteres, o que é comum para dados baseados em texto, como nomes, categorias ou IDs.	"electronics", "BrandA"
ARRAY_BOOL / array_bool	Utilizado para indexar uma matriz de valores booleanos.	[true, false, true]
ARRAY_DOUBLE / array_double	Utilizado para indexar uma matriz de valores numéricos.	[1.2, 3.14, 42]
ARRAY_VARCHAR / array_varchar	Utiliza-se para indexar um conjunto de cadeias de caracteres, o que é ideal para uma lista de etiquetas ou palavras-chave.	["tag1", "tag2", "tag3"]
JSON / json	Objectos ou sub-objectos JSON inteiros com inferência automática de tipo e nivelamento. A indexação de objectos JSON inteiros aumenta o tamanho do índice. Para cenários com muitas chaves, considere a fragmentação de JSON.	Qualquer objeto JSON

Funções de conversão suportadas

Se a chave do campo JSON contiver valores num formato incorreto (por exemplo, números armazenados como cadeias de caracteres), pode passar uma função de conversão para o argumento json_cast_function para converter estes valores no momento da indexação.

As funções de conversão não diferenciam maiúsculas de minúsculas. As seguintes funções são suportadas:

Função Cast	Converte de → para	Caso de uso
STRING_TO_DOUBLE / string_to_double	String → Numérico (double)	Converter "99.99" to 99.99

Criar índices JSON

Esta secção demonstra como criar índices em diferentes tipos de dados JSON utilizando exemplos práticos. Todos os exemplos utilizam a estrutura JSON de amostra apresentada abaixo e assumem que já estabeleceu uma ligação ao MilvusClient com um esquema de coleção corretamente definido.

Exemplo de estrutura JSON

{
  "metadata": { 
    "category": "electronics",
    "brand": "BrandA",
    "in_stock": true,
    "price": 99.99,
    "string_price": "99.99",
    "tags": ["clearance", "summer_sale"],
    "supplier": {
      "name": "SupplierX",
      "country": "USA",
      "contact": {
        "email": "support@supplierx.com",
        "phone": "+1-800-555-0199"
      }
    }
  }
}

Configuração básica

Antes de criar qualquer índice JSON, prepare seus parâmetros de índice:

# Prepare index params
index_params = MilvusClient.prepare_index_params()

Exemplo 1: indexar uma chave JSON simples

Crie um índice no campo category para permitir uma filtragem rápida por categoria de produto:

index_params.add_index(
    field_name="metadata",
    index_type="AUTOINDEX", # Must be set to AUTOINDEX or INVERTED for JSON path indexing
    index_name="category_index",  # Unique index name
    params={
        "json_path": 'metadata["category"]', # Path to the JSON key
        "json_cast_type": "varchar" # Data cast type
    }
)

Exemplo 2: Indexar uma chave aninhada

Crie um índice no campo email profundamente aninhado para pesquisas de contactos de fornecedores:

# Index the nested key
index_params.add_index(
    field_name="metadata",
    index_type="AUTOINDEX", # Must be set to AUTOINDEX or INVERTED for JSON path indexing
    index_name="email_index", # Unique index name
    params={
        "json_path": 'metadata["supplier"]["contact"]["email"]', # Path to the nested JSON key
        "json_cast_type": "varchar" # Data cast type
    }
)

Exemplo 3: Converter o tipo de dados no momento do índice

Por vezes, os dados numéricos são armazenados por engano como cadeias de caracteres. Utilize a função de conversão STRING_TO_DOUBLE para os converter e indexar corretamente:

# Convert string numbers to double for indexing
index_params.add_index(
    field_name="metadata",
    index_type="AUTOINDEX", # Must be set to AUTOINDEX or INVERTED for JSON path indexing
    index_name="string_to_double_index", # Unique index name
    params={
        "json_path": 'metadata["string_price"]', # Path to the JSON key to be indexed
        "json_cast_type": "double", # Data cast type
        "json_cast_function": "STRING_TO_DOUBLE" # Cast function; case insensitive
    }
)

Importante: Se a conversão falhar para qualquer documento (por exemplo, uma cadeia de caracteres não numérica como "invalid"), o valor desse documento será excluído do índice e não aparecerá nos resultados filtrados.

Exemplo 4: Indexar objetos inteiros

Indexe o objeto JSON completo para permitir consultas em qualquer campo dentro dele. Quando você usa json_cast_type="JSON", o sistema automaticamente:

• Achata a estrutura JSON: Os objectos aninhados são convertidos em caminhos planos para uma indexação eficiente

• Infere tipos de dados: Cada valor é automaticamente categorizado como numérico, cadeia de caracteres, booleano ou data com base no seu conteúdo

• Cria uma cobertura abrangente: Todas as chaves e caminhos aninhados dentro do objeto tornam-se pesquisáveis

Para a estrutura JSON de amostra acima, indexe todo o objeto metadata:

# Index the entire JSON object
index_params.add_index(
    field_name="metadata",
    index_type="AUTOINDEX",
    index_name="metadata_full_index",
    params={
        "json_path": "metadata",
        "json_cast_type": "JSON"
    }
)

Também é possível indexar apenas uma parte da estrutura JSON, como todas as informações de supplier:

# Index a sub-object
index_params.add_index(
    field_name="metadata",
    index_type="AUTOINDEX", 
    index_name="supplier_index",
    params={
        "json_path": 'metadata["supplier"]',
        "json_cast_type": "JSON"
    }
)

Aplicar a configuração do índice

Depois de definir todos os seus parâmetros de índice, aplique-os à sua coleção:

# Apply all index configurations to the collection
MilvusClient.create_index(
    collection_name="your_collection_name",
    index_params=index_params
)

Assim que a indexação for concluída, suas consultas de campo JSON usarão automaticamente esses índices para um desempenho mais rápido.

PERGUNTAS FREQUENTES

O que acontece se a expressão de filtro de uma consulta usar um tipo diferente do tipo de elenco indexado?

Se a expressão do filtro usar um tipo diferente do tipo do índice json_cast_type, o Milvus não usará o índice e poderá voltar a uma pesquisa de força bruta mais lenta se os dados permitirem. Para obter o melhor desempenho, alinhe sempre a sua expressão de filtro com o tipo de conversão do índice. Por exemplo, se um índice numérico for criado com json_cast_type="double", apenas as condições de filtro numéricas aproveitarão o índice.

Ao criar um índice JSON, o que acontece se uma chave JSON tiver tipos de dados inconsistentes em diferentes entidades?

Tipos inconsistentes podem levar à indexação parcial. Por exemplo, se um campo metadata["price"] for armazenado como um número (99.99) e uma cadeia de caracteres ("99.99") e você criar um índice com json_cast_type="double", somente os valores numéricos serão indexados. As entradas em forma de cadeia de caracteres serão ignoradas e não aparecerão nos resultados do filtro.

Posso criar vários índices na mesma chave JSON?

Não, cada chave JSON suporta apenas um índice. Tem de escolher um único json_cast_type que corresponda aos seus dados. No entanto, pode criar um índice em todo o objeto JSON e um índice numa chave aninhada dentro desse objeto.

Um campo JSON suporta a definição de um valor predefinido?

Não, os campos JSON não suportam valores predefinidos. No entanto, pode definir nullable=True ao definir o campo para permitir entradas vazias. Para obter mais informações, consulte Nullable & Default.