Como usar APIs do desenvolvedor para executar modelos sequencialmente¶

Análises complexas podem exigir que vários modelos sejam executados em uma ordem específica, às vezes usando a saída de um modelo como entrada de outro. Um provedor pode criar uma cadeia de modelos para definir uma sequência de modelos a serem executados em uma ordem específica. Ao definir esta cadeia de modelos, o provedor pode especificar se os resultados de um modelo específico estarão disponíveis para modelos subsequentes na cadeia.

Um usuário de sala limpa executa uma cadeia de modelos para realizar uma análise que executa os modelos na cadeia em sua ordem predefinida.

Sobre resultados intermediários¶

Se um provedor quiser que os resultados de um modelo estejam disponíveis para modelos subsequentes na cadeia de modelos, ele poderá criar um cache para os resultados do modelo. Cada modelo com cache também tem um tempo de expiração para esse cache.

Se um provedor especificar que um modelo tem um cache, na primeira vez que um usuário executar a cadeia de modelos, os resultados desse modelo serão armazenados em uma tabela dentro da sala limpa. Esta tabela subjacente só é acessível à própria sala limpa. Na próxima vez que um usuário executar a cadeia de modelos, Snowflake Data Clean Rooms verifica se o cache expirou antes de executar o modelo. O modelo com os resultados armazenados em cache não será executado novamente, a menos que o cache tenha expirado.

Os modelos subsequentes na cadeia de modelos podem usar o cache como entrada incluindo o parâmetro Jinja apropriado no modelo.

Definição de uma cadeia de modelos¶

Um provedor usa o comando provider.add_template_chain para criar uma cadeia de modelos. Os modelos que o provedor deseja adicionar à nova cadeia de modelos devem existir antes de criar a cadeia de modelos.

O comando provider.add_template_chain aceita os seguintes argumentos:

Nome de uma sala limpa (string).
Nome da cadeia de modelos (string).
Modelos na cadeia de modelos (matriz de objetos JSON).

Para um exemplo de uso do comando provider.add_template_chain para criar uma cadeia de modelos, consulte Exemplo.

Adição de modelos à cadeia de modelos¶

O provedor define quais modelos fazem parte de uma cadeia de modelos passando uma matriz de objetos JSON para provider.add_template_chain, onde cada objeto JSON representa um modelo. A ordem dos objetos JSON determina a ordem em que os modelos são executados.

O objeto JSON para um modelo pode incluir os seguintes campos:

template_name (string)

Especifica o modelo que está sendo adicionado à cadeia de modelos. O modelo já deve existir.

Este campo é obrigatório.

cache_results (boolean)

Determina se os resultados do modelo são armazenados em cache para que outros modelos na cadeia de modelos possam acessá-los. Para armazenar os resultados em cache, especifique TRUE.

Este campo é obrigatório. Se TRUE, os campos output_table_name e cache_expiration_hours também são obrigatórios.

output_table_name (string)

Quando cache_results = TRUE, especifica o nome da tabela Snowflake onde os resultados do modelo são armazenados.

Este campo é obrigatório se cache_results = TRUE.

jinja_output_table_param (string)

Quando cache_results = TRUE, especifica o nome do parâmetro Jinja que outros modelos devem incluir para aceitar os resultados armazenados em output_table_name.

Este campo é opcional.

cache_expiration_hours (inteiro)

Quando cache_results = TRUE, especifica o número de horas antes que os resultados no cache sejam descartados. Quando o cache expira, na próxima vez que a cadeia de modelos for executada, o cache será atualizado com os resultados do modelo.

Este campo é obrigatório se cache_results = TRUE.

Exemplo¶

Neste exemplo, o provedor deseja:

Criar uma cadeia de modelos insights_chain na sala limpa collab_clean_room.
Definir a cadeia de modelos para que o modelo crosswalk seja executado antes do modelo transaction_insights.
Armazenar em cache os resultados do modelo crosswalk para que eles possam ser usados como entrada para o modelo transaction_insights.

CALL samooha_by_snowflake_local_db.provider.add_template_chain(
  'collab_clean_room',
  'insights_chain',
  [
    {
      'template_name': 'crosswalk',
      'cache_results': True,
      'output_table_name': 'crosswalk',
      'jinja_output_table_param': 'crosswalk_table_name',
      'cache_expiration_hours': 2190
    },
    {
      'template_name': 'transaction_insights',
      'cache_results': False
    }
  ]
);

Copy

Para mais informações sobre cada objeto JSON, consulte Adição de modelos à cadeia de modelos.

Execução de uma cadeia de modelos¶

Um usuário de sala limpa executa o comando consumer.run_analysis para executar uma cadeia de modelos, que é o mesmo comando usado para executar um único modelo. A execução da cadeia de modelos executa cada modelo na cadeia em sua ordem predefinida para obter o resultado final.

O comando consumer.run_analysis aceita argumentos que ele passa para os modelos Jinja na cadeia de modelos. Você pode determinar quais argumentos são esperados pelos modelos na cadeia executando o comando consumer.get_arguments_from_template_chain.

Os argumentos passados para consumer.run_analysis podem ser específicos para um modelo específico na cadeia ou podem ser argumentos para cada modelo na cadeia.

Argumentos universais

Se você quiser passar um argumento para cada modelo na cadeia de modelos, a sintaxe é a mesma usada para consumer.run_analysis para executar um único modelo. Por exemplo, o comando a seguir passa o valor do argumento where_clause para todos os modelos na cadeia de modelos:

CALL samooha_by_snowflake_local_db.consumer.run_analysis(
  'collab_clean_room',
  'insights_chain',
  ['MY_CONSUMER_DB.C_SCHEMA.CONVERSIONS'],
  ['PROVIDER_DB.P_SCHEMA.EXPOSURES'],
  object_construct(
    'where_clause', 'p.EMAIL=c.EMAIL'
  )
);

Copy

Argumentos específicos do modelo

Se você quiser passar um argumento para um modelo específico, adicione outro object_construct como filho do object_construct de nível superior com o nome do modelo como nome do campo. Por exemplo, o comando a seguir passa o valor do argumento dimensions somente para o modelo crosswalk_template.

CALL samooha_by_snowflake_local_db.consumer.run_analysis(
  'collab_clean_room',
  'insights_chain',
  ['MY_CONSUMER_DB.C_SCHEMA.CONVERSIONS'],
  ['PROVIDER_DB.P_SCHEMA.EXPOSURES'],
  object_construct(
    'where_clause', 'p.EMAIL=c.EMAIL',
    'crosswalk_template', object_construct(
      'dimensions', ['p.CAMPAIGN']
    )
  )
);

Copy

Comandos de cadeia de modelos¶

Você pode usar os seguintes comandos para trabalhar com cadeias de modelos:

Comando	Descrição
`provider.add_template_chain`	Cria uma nova cadeia de modelos.
`provider.view_added_template_chains` `consumer.view_added_template_chains`	Retorna todas as cadeias de modelos que foram adicionadas à sala limpa.
`provider.view_template_chain_definition` `consumer.view_template_chain_definition`	Retorna a definição de uma cadeia de modelos.
`provider.clear_template_chain`	Descarta uma corrente de modelos da sala limpa.
`provider.clear_all_template_chains`	Descarta todas as cadeias de modelos da sala limpa.
`consumer.get_arguments_from_template_chain`	Retorna os argumentos esperados para todos os modelos na cadeia de modelos.

Para obter mais informações sobre esses comandos, consulte o seguinte: