Extrair dados estruturados

A função ai.extract é uma ferramenta de IA integrada do AlloyDB que extrai detalhes estruturados especificados de textos não estruturados com base em um esquema fornecido. Ao incorporar esse recurso diretamente no banco de dados, o AlloyDB para PostgreSQL permite processar dados não estruturados sem criar pipelines complexos de extração, transformação e carregamento (ETL) ou integrações de serviços externos.

A função de extração de dados oferece os seguintes benefícios:

  • Escalonabilidade: oferece suporte ao lote inteligente para funções de IA, também conhecido como aceleração de funções de IA, que é um recurso de otimização automática da execução de consultas na IA do AlloyDB que agrupa de forma transparente chamadas de funções de IA escalares individuais, linha por linha, em solicitações de modelo em lote em segundo plano durante a execução da consulta. Também oferece suporte ao processamento baseado em matrizes e cursores para processar milhares de linhas com eficiência.
  • Abstração: fornece uma abstração de alto nível que gerencia automaticamente a invocação de modelos e a preparação de dados.

A função de extração de dados da IA do AlloyDB é compatível com vários casos de uso, incluindo os seguintes:

  • Saúde: analise notas médicas de texto livre em campos de formato estruturado, como nomes de pacientes, sintomas e medicamentos.
  • Imobiliário: transforme descrições de propriedades não estruturadas em pontos de dados específicos, como tipo de propriedade e número de quartos.
  • Tecnologia jurídica: identifique e extraia automaticamente termos críticos, como legislação aplicável e limites de responsabilidade, de documentos jurídicos longos.
  • Operações financeiras: processe o texto transcrito de faturas para extrair com precisão metadados e valores totais em um formato consistente.

Antes de começar

Verifique se você atende aos seguintes requisitos antes de usar a função ai.extract:

  • Versão do PostgreSQL: a função ai.extract é compatível com o PostgreSQL versão 18 e mais recentes. Verifique se o cluster do AlloyDB está executando o PostgreSQL 18 ou mais recente. Para mais informações, consulte Versões de banco de dados compatíveis.
  • Versão da extensão: verifique se você tem a versão mais recente da extensão google_ml_integration (versão 1.6.1 ou mais recente) instalada com a funcionalidade de pré-lançamento ativada.

Ativar a extensão

Verifique se você tem a versão mais recente da extensão google_ml_integration (versão 1.6.1 ou mais recente) instalada com a funcionalidade de pré-lançamento ativada.

Para ativar as flags google_ml_integration.enable_ai_query_engine e google_ml_integration.enable_preview_ai_functions no AlloyDB, use o comando SET. Essas flags controlam o acesso ao mecanismo de consulta de IA e às funções de IA em pré-lançamento, como ai.extract. O valor padrão dessas flags é off.

  1. Verifique se a extensão google_ml_integration é da versão 1.6.1 ou mais recente. Verifique a versão executando o seguinte:

    SELECT extversion FROM pg_extension WHERE extname = 'google_ml_integration';

  2. Para ativar as flags na sessão atual, em todo o banco de dados ou em todos os bancos de dados de uma instância, execute uma ou mais das seguintes tarefas:

    • Para ativar as flags na sessão atual, execute o seguinte:

      SET google_ml_integration.enable_ai_query_engine = 'on';
SET google_ml_integration.enable_preview_ai_functions = 'on';

      Essa mudança não exige a reinicialização do banco de dados.

    • Para ativar as flags de forma persistente para um banco de dados específico, execute o seguinte:

      ALTER DATABASE DATABASE_NAME SET google_ml_integration.enable_ai_query_engine = 'on';
ALTER DATABASE DATABASE_NAME SET google_ml_integration.enable_preview_ai_functions = 'on';

    • Para ativar as flags em todos os bancos de dados de uma instância, defina as flags de banco de dados google_ml_integration.enable_ai_query_engine e google_ml_integration.enable_preview_ai_functions como on usando o comando gcloud alloydb instances update:

      gcloud alloydb instances update INSTANCE_ID           --database-flags google_ml_integration.enable_ai_query_engine=on,google_ml_integration.enable_preview_ai_functions=on           --region=REGION_ID           --cluster=CLUSTER_ID           --project=PROJECT_ID

      Para mais informações, consulte Configurar flags de banco de dados.

Ativar o lote inteligente para funções de IA

Para acelerar o tempo total de execução de consultas ao executar ai.extract escalar em várias linhas, ative o lote inteligente para funções de IA definindo a flag de banco de dados google_ml_integration.enable_ai_function_acceleration como on:

SET google_ml_integration.enable_ai_function_acceleration = 'on';

Quando essa flag está ativada, o AlloyDB agrupa automaticamente chamadas escalares individuais de ai.extract em lotes inteligentes em segundo plano.

Criar uma tabela de exemplo

Para seguir os exemplos de função de extração neste documento, crie uma tabela e preencha-a com os dados de amostra a seguir.

CREATE TABLE IF NOT EXISTS sales_leads (
    lead_id INT PRIMARY KEY,
    raw_transcript TEXT,
    lead_status VARCHAR(20)
);

INSERT INTO sales_leads (lead_id, raw_transcript, lead_status) VALUES
(1, 'Spoke with Alex R., Director of IT at Example Organization. They are looking to upgrade their cloud storage.', 'new'),
(2, 'Call with Kai L., Senior DevOps Engineer at Example Organization. They are currently using MySQL and Redis. Interested in automating enterprise database backups, cross-region replication, and automated scaling.', 'new'),
(3, 'Meeting with Taylor K., VP of Engineering at Example Organization. They need a scalable managed PostgreSQL database for their analytics platform. Budget is approved for Q3 launch.', 'new');

Extrair dados estruturados de uma única string

Para extrair detalhes estruturados de uma única entrada de texto, use a versão escalar de ai.extract. Para mais informações, consulte a referência de ai.extract.

SELECT ai.extract(
  input => 'TEXT_CONTENT',
  output_schema => 'OUTPUT_SCHEMA',
  model_id => 'MODEL_ID' -- Optional. The default value is gemini-3.5-flash-lite.
);

Extrair dados de uma tabela

O exemplo a seguir extrai informações estruturadas da coluna da tabela raw_transcript:

SELECT
  lead_id,
  ai.extract(
    input => raw_transcript,
    output_schema => '{"contact_name": {"type": "string"}, "company_name": {"type": "string"}, "job_title": {"type": "string"}}'
   ) AS extracted_info
FROM
  sales_leads
WHERE
  lead_status = 'new';

Extrair campos com base no esquema JSON fornecido

O exemplo a seguir extrai campos específicos do texto de entrada com base no esquema JSON fornecido:

SELECT ai.extract(
  input => 'Spoke with Alex R., Director of IT at Example Organization. They are looking to upgrade their cloud storage.',
  output_schema => '{"contact_name": {"type": "string"}, "job_title": {"type": "string"}, "company_name": {"type": "string"}, "need": {"type": "string"}}'
);

Veja um exemplo de saída:

{
  "contact_name": "Alex R.",
  "job_title": "Director of IT",
  "company_name": "Example Organization",
  "need": "upgrade cloud storage"
}

Extrair campos com base em um comando de linguagem natural

O exemplo a seguir extrai detalhes de leads de vendas usando um esquema de texto descritivo:

SELECT ai.extract(
  input => 'Meeting with Taylor K., VP of Engineering at Example Organization. They need a scalable managed PostgreSQL database for their analytics platform. Budget is approved for Q3 launch.',
  output_schema => 'Extract the following details as a clean, line-by-line list: Contact Name, Job Title, Company Name, Technical Requirement, Target Use Case, and Timeline.'
);

Veja um exemplo de saída:

Contact Name: Taylor K.
Job Title: VP of Engineering
Company Name: Example Organization
Technical Requirement: Scalable managed PostgreSQL database
Target Use Case: Analytics platform
Timeline: Q3 launch

Extrair campos com matrizes

O exemplo a seguir extrai vários valores em campos de matriz com base no esquema de saída:

SELECT ai.extract(
  input => 'Call with Kai L., Senior DevOps Engineer at Example Organization. They are currently using MySQL and Redis. Interested in automating enterprise database backups, cross-region replication, and automated scaling.',
  output_schema => '{"contact_name": {"type": "string"}, "company_name": {"type": "string"}, "current_technologies": {"type": "array", "items": {"type": "string"}}, "interested_features": {"type": "array", "items": {"type": "string"}}}'
);

Veja um exemplo de saída:

{
  "contact_name": "Kai L.",
  "company_name": "Example Organization",
  "current_technologies": ["MySQL", "Redis"],
  "interested_features": ["enterprise database backups", "cross-region replication", "automated scaling"]
}

Extrair dados estruturados em lotes

Para acelerar o tempo total de execução de consultas em conjuntos de dados maiores, use a versão da função baseada em matriz para processar várias entradas em uma única chamada. Para mais informações, consulte a referência de ai.extract.

SELECT ai.extract(
  inputs => TEXT[],
  output_schema => TEXT,
  batch_size => INT, -- Optional. The default value is 10.
  model_id => VARCHAR(100) -- Optional. The default value is gemini-3.5-flash-lite.
);

O exemplo a seguir extrai detalhes estruturados de vários registros:

SELECT
  ai.extract(
    inputs => array_agg(raw_transcript ORDER BY lead_id),
    output_schema => '{"contact_name": {"type": "string"}, "company_name": {"type": "string"}, "job_title": {"type": "string"}}',
    batch_size => 4
  )
FROM sales_leads;

Extrair dados estruturados usando cursores

A função baseada em cursor é adequada para processar grandes conjuntos de dados, porque permite que o sistema transmita dados pelo modelo de IA em lotes gerenciáveis, sem exigir que todos os dados sejam carregados na memória de uma só vez. Para mais informações, consulte a referência sobre ai.extract.

A assinatura da função para a versão baseada em cursor de ai.extract é a seguinte:

CREATE OR REPLACE FUNCTION ai.extract(
    input_cursor REFCURSOR,
    output_schema TEXT,
    batch_size INT DEFAULT NULL,
    model_id VARCHAR(100) DEFAULT NULL)
  RETURNS REFCURSOR

O exemplo a seguir mostra como alimentar dados para a função ai.extract linha por linha usando um cursor:

DO $$
DECLARE
    input_cur REFCURSOR;
    output_cur REFCURSOR;
    result_record RECORD;
BEGIN
    -- Open the input cursor with the data to process
    OPEN input_cur FOR
        SELECT raw_transcript
        FROM sales_leads
        WHERE lead_status = 'new';

    -- Call ai.extract passing the input cursor
    output_cur := ai.extract(
        input_cursor => input_cur,
        output_schema => '{"contact_name": "string", "company_name": "string", "job_title": "string"}',
        batch_size => 10
    );

    -- Loop through the output cursor (columns: input TEXT, output TEXT)
    LOOP
        FETCH output_cur INTO result_record;
        EXIT WHEN NOT FOUND;

        RAISE NOTICE 'Extracted Data: %', result_record.output;
    END LOOP;

    CLOSE input_cur;
    CLOSE output_cur;
END $$;

A seguir