DOCUMENTATION
/
Introdução
Guias
Desenvolvedor
Referência
Lançamentos
Tutoriais
Snowflake Open Catalog
Status

Tutorial 1: Crie um aplicativo de pesquisa simples com o Cortex Search

GuiasAI e ML do SnowflakeCortex SearchTutoriaisTutorial 1: Crie um aplicativo de pesquisa simples

Tutorial 1: Crie um aplicativo de pesquisa simples com o Cortex Search¶

Introdução¶

Este tutorial descreve como começar a usar o Cortex Search para um aplicativo de pesquisa simples.

O que você aprenderá¶

  • Crie um Cortex Search Service a partir de um conjunto de dados de listagens AirBnb.

  • Crie um aplicativo Streamlit in Snowflake que permita consultar seu Cortex Search Service.

Pré-requisitos¶

Os seguintes pré-requisitos são necessários para concluir este tutorial:

  • Você tem uma conta Snowflake e um usuário com uma função que concede os privilégios necessários para criar um banco de dados, tabelas, objetos de warehouse virtual, Cortex Search Services e aplicativos Streamlit.

Consulte o Snowflake em 20 minutos para obter instruções para atender a estes requisitos.

Etapa 1: Configuração¶

Como obter dados da amostra¶

Você usará um conjunto de dados de amostra hospedado no Huggingface, baixado como um único arquivo JSON. Baixe o arquivo diretamente do seu navegador seguindo este link:

  • Conjunto de dados de listagens AirBnB

Nota

Em um configuração não tutorial, você traria seus próprios dados, possivelmente já em uma tabela Snowflake.

Criação do banco de dados, tabelas e warehouses¶

Execute as seguintes instruções para criar um banco de dados e um warehouse virtual necessários para este tutorial. Depois de concluir o tutorial, você poderá descartar estes objetos.

CREATE DATABASE IF NOT EXISTS cortex_search_tutorial_db;

CREATE OR REPLACE WAREHOUSE cortex_search_tutorial_wh WITH
     WAREHOUSE_SIZE='X-SMALL'
     AUTO_SUSPEND = 120
     AUTO_RESUME = TRUE
     INITIALLY_SUSPENDED=TRUE;
Copy

Observe o seguinte:

  • A instrução CREATE DATABASE cria um banco de dados. O banco de dados inclui automaticamente um esquema chamado “public”.

  • A instrução CREATE WAREHOUSE cria um warehouse inicialmente suspenso. A instrução também define AUTO_RESUME = true, que inicia automaticamente o warehouse quando você executa instruções SQL que exigem recursos computacionais.

Etapa 2: Carregamento de dados para o Snowflake¶

Antes de criar um serviço de pesquisa, você deve carregar os dados de exemplo no Snowflake.

Você pode carregar o conjunto de dados em Snowsight ou usando SQL. Para carregar em Snowsight:

  1. Selecione o botão + Create acima da barra de navegação esquerda.

  2. Em seguida selecione Table » From File.

    Adição de dados na UI do Snowsight
  3. Selecione seu warehouse recém-criado como um warehouse para sua tabela no menu suspenso no canto superior direito.

  4. Arraste e solte o arquivo de dados JSON na caixa de diálogo.

  5. Selecione o banco de dados que você criou acima e especifique o esquema PUBLIC.

  6. Por fim, especifique a criação de uma nova tabela chamada airbnb_listings e selecione Next.

    Adição de dados na UI do Snowsight
  7. Na caixa de diálogo Load Data into Table, faça os seguintes ajustes. Primeiro, desmarque as colunas image_embeddings, images e text_embeddings, pois elas não se aplicam a este tutorial. Segundo, ajuste o tipo de dados do campo amenities para o tipo ARRAY.

    Adição de dados na UI do Snowsight
    Adição de dados na UI do Snowsight
  8. Depois de fazer esses ajustes, selecione Load para prosseguir.

  9. Após um breve momento, você verá uma página de confirmação mostrando que os dados foram carregados.

    Adição de dados na UI do Snowsight
  10. Selecione Query Data para abrir uma nova planilha do Snowsight que você usará na próxima etapa.

Etapa 3: Criação do serviço de pesquisa¶

Crie um serviço de pesquisa em nossa nova tabela executando o seguinte comando SQL.

CREATE OR REPLACE CORTEX SEARCH SERVICE cortex_search_tutorial_db.public.airbnb_svc
ON listing_text
ATTRIBUTES room_type, amenities
WAREHOUSE = cortex_search_tutorial_wh
TARGET_LAG = '1 hour'
AS
    SELECT
        room_type,
        amenities,
        price,
        cancellation_policy,
        ('Summary\n\n' || summary || '\n\n\nDescription\n\n' || description || '\n\n\nSpace\n\n' || space) as listing_text
    FROM
    cortex_search_tutorial_db.public.airbnb_listings;
Copy
Vamos analisar os argumentos neste comando:
  • O parâmetro ON especifica a coluna para as consultas pesquisarem. Neste caso, é o listing_text, que é gerado na consulta de origem como uma concatenação de várias colunas de texto na tabela base.

  • O parâmetro ATTRIBUTES especifica as colunas nas quais você poderá filtro os resultados da pesquisa. Este exemplo filtra em room_type e amenities ao emitir consultas para a coluna listing_text.

  • Os parâmetros WAREHOUSE e TARGET_LAG especificam o warehouse fornecido pelo usuário e o nível de atualização desejado do serviço de pesquisa, respectivamente. Este exemplo especifica o uso do warehouse cortex_search_tutorial_wh para criar o índice e executar atualizações, além de manter o serviço não mais do que '1 hour' atrás da tabela de origem AIRBNB_LISTINGS.

  • O campo AS define a tabela de origem para o serviço. Este exemplo concatena várias colunas de texto na tabela original na coluna de pesquisa listing_text para que as consultas possam pesquisar em vários campos.

Etapa 4: Criação de um aplicativo Streamlit¶

Você pode consulta o serviço com Python SDK (usando o pacote Python snowflake). Este tutorial demonstra o uso do Python SDK em um aplicativo Streamlit in Snowflake.

Primeiro, certifique-se de que sua função de Snowsight UI global seja a mesma que a função usada para criar o serviço na etapa de criação do serviço.

  1. Faça login no Snowsight.

  2. Selecione Projects » Streamlit no menu de navegação do lado esquerdo.

  3. Selecione + Streamlit App.

  4. Importante: selecione o banco de dados cortex_search_tutorial_db e o esquema public para o local do aplicativo.

  5. No painel esquerdo do editor Streamlit in Snowflake, selecione Packages e adicione snowflake (versão >= 0.8.0) para instalar o pacote em seu aplicativo.

  6. Substitua o código do aplicativo de exemplo pelo seguinte aplicativo Streamlit:

    # Import python packages
    import streamlit as st
    from snowflake.core import Root
    from snowflake.snowpark.context import get_active_session
    
    # Constants
    DB = "cortex_search_tutorial_db"
    SCHEMA = "public"
    SERVICE = "airbnb_svc"
    BASE_TABLE = "cortex_search_tutorial_db.public.airbnb_listings"
    ARRAY_ATTRIBUTES = {"AMENITIES"}
    
    
    def get_column_specification():
        """
        Returns the name of the search column and a list of the names of the attribute columns
        for the provided cortex search service
        """
        session = get_active_session()
        search_service_result = session.sql(f"DESC CORTEX SEARCH SERVICE {DB}.{SCHEMA}.{SERVICE}").collect()[0]
        st.session_state.attribute_columns = search_service_result.attribute_columns.split(",")
        st.session_state.search_column = search_service_result.search_column
        st.session_state.columns = search_service_result.columns.split(",")
    
    def init_layout():
        st.title("Cortex AI Search")
        st.markdown(f"Querying service: `{DB}.{SCHEMA}.{SERVICE}`".replace('"', ''))
    
    def query_cortex_search_service(query, filter={}):
        """
        Queries the cortex search service in the session state and returns a list of results
        """
        session = get_active_session()
        cortex_search_service = (
            Root(session)
            .databases[DB]
            .schemas[SCHEMA]
            .cortex_search_services[SERVICE]
        )
        context_documents = cortex_search_service.search(
            query,
            columns=st.session_state.columns,
            filter=filter,
            limit=st.session_state.limit)
        return context_documents.results
    
    @st.cache_data
    def distinct_values_for_attribute(col_name, is_array_attribute=False):
        session = get_active_session()
        if is_array_attribute:
            values = session.sql(f'''
            SELECT DISTINCT value FROM {BASE_TABLE},
            LATERAL FLATTEN(input => {col_name})
            ''').collect()
        else:
            values = session.sql(f"SELECT DISTINCT {col_name} AS VALUE FROM {BASE_TABLE}").collect()
        return [ x["VALUE"].replace('"', "") for x in values ]
    
    def init_search_input():
        st.session_state.query = st.text_input("Query")
    
    def init_limit_input():
        st.session_state.limit = st.number_input("Limit", min_value=1, value=5)
    
    def init_attribute_selection():
        st.session_state.attributes = {}
        for col in st.session_state.attribute_columns:
            is_multiselect = col in ARRAY_ATTRIBUTES
            st.session_state.attributes[col] = st.multiselect(
                col,
                distinct_values_for_attribute(col, is_array_attribute=is_multiselect)
            )
    
    def display_search_results(results):
        """
        Display the search results in the UI
        """
        st.subheader("Search results")
        for i, result in enumerate(results):
            result = dict(result)
            container = st.expander(f"[Result {i+1}]", expanded=True)
    
            # Add the result text.
            container.markdown(result[st.session_state.search_column])
    
            # Add the attributes.
            for column, column_value in sorted(result.items()):
                if column == st.session_state.search_column:
                    continue
                container.markdown(f"**{column}**: {column_value}")
    
    def create_filter_object(attributes):
        """
        Create a filter object for the search query
        """
        and_clauses = []
        for column, column_values in attributes.items():
            if len(column_values) == 0:
                continue
            if column in ARRAY_ATTRIBUTES:
                for attr_value in column_values:
                    and_clauses.append({"@contains": { column: attr_value }})
            else:
                or_clauses = [{"@eq": {column: attr_value}} for attr_value in column_values]
                and_clauses.append({"@or": or_clauses })
    
        return {"@and": and_clauses} if and_clauses else {}
    
    
    def main():
        init_layout()
        get_column_specification()
        init_attribute_selection()
        init_limit_input()
        init_search_input()
    
        if not st.session_state.query:
            return
        results = query_cortex_search_service(
            st.session_state.query,
            filter = create_filter_object(st.session_state.attributes)
        )
        display_search_results(results)
    
    
    if __name__ == "__main__":
        st.set_page_config(page_title="Cortex AI Search and Summary", layout="wide")
        main()
    
    Copy

Aqui está uma breve análise dos principais componentes do código Streamlit-in-Snowflake acima:

  • get_column_specification usa uma consulta DESCRIBE SQL para obter informações sobre os atributos disponíveis no serviço de pesquisa e os armazena no estado Stremalit.

  • init_layout configura o cabeçalho e a introdução da página.

  • query_cortex_search_service manipula a consulta do Cortex Search Service por meio da biblioteca cliente Python.

  • create_filter_object processa atributos de filtro selecionados do formulário Streamlit nos objetos corretos a serem usados pela biblioteca Python para consultar o Cortex Search.

  • distinct_values_for_attribute determina quais valores são possíveis para cada atributo filtrável para preencher os menus suspensos.

  • init_search_input, init_limit_input, init_attribute_selection inicializam entradas para a consulta de pesquisa, limite de número de resultados e filtros de atributo.

  • display_search_results formata os resultados da pesquisa em elementos Markdown exibidos na página de resultados.

Etapa 5: Limpeza¶

Limpeza (opcional)¶

Execute os seguintes comandos DROP <objeto> para retornar o sistema ao seu estado antes de iniciar o tutorial:

DROP DATABASE IF EXISTS cortex_search_tutorial_db;
DROP WAREHOUSE IF EXISTS cortex_search_tutorial_wh;
Copy

Descartar o banco de dados remove automaticamente todos os objetos do banco de dados filho, tais como tabelas.

Próximos passos¶

Parabéns! Você criou com sucesso um aplicativo de pesquisa simples em dados de texto no Snowflake. Você pode prosseguir para o Tutorial 2 para ver como aplicar camadas no Cortex LLM Functions para criar um chatbot AI com o Cortex Search.

Recursos adicionais¶

Além disso, você pode continuar aprendendo usando os seguintes recursos:

  • Visão geral do Cortex Search

  • Consulta ao Cortex Search Service

Esta página foi útil?

Visite Snowflake
Participe da conversa
Como desenvolver com Snowflake
Compartilhe seu feedback
Leia as novidades em nosso blog
Tenha sua própria certificação
Aviso de privacidadeTermos do site© 2025 Snowflake, Inc. Todos os direitos reservados.
Linguagem: Português
  • English
  • Français
  • Deutsch
  • 日本語
  • 한국어
  • Português