Guia de migração

Importante: este guia é destinado a usuários que estão migrando da versão inicial de prévia . Todos os outros usuários já usam listagens e não precisam migrar.

Esta versão do Insights de Lugares de 4 de setembro de 2025 inclui as seguintes mudanças da versão inicial:

• Oferece suporte à capacidade de assinar o Insights de Lugares no BigQuery local de sua escolha.

• Move os conjuntos de dados do Insights de Lugares das data clean rooms para as listagens do BigQuery Data Exchange.

• Os campos de endereço no esquema do conjunto de dados separam os campos id e name em campos de string ou matriz de strings discretos.

Observação: para aproveitar os novos campos de endereço, é necessário migrar para as listagens. Se você decidir não migrar para as listagens e continuar usando as data clean rooms, continue usando os campos de endereço e o esquema do conjunto de dados da versão inicial.

Migrar para listagens

A versão inicial de prévia do Places Insights implantou dados em data clean rooms do BigQuery . Com a versão de 4 de setembro de 2025, movemos os conjuntos de dados para as listagens do BigQuery para que você possa assinar o conjunto de dados em uma região específica do BigQuery. Essa mudança não tem impacto nos recursos do produto e na usabilidade do Insights de Lugares.

Para assinar o Insights de Lugares em uma região específica, é necessário assinar as novas listagens no BigQuery Sharing. Depois de assinar as novas listagens, não é necessário modificar suas consultas SQL. Elas ainda funcionarão da mesma maneira.

• Novos usuários:se você é um novo usuário do Insights de Lugares, siga as etapas em Configurar o Insights de Lugares para configurar seu ambiente de desenvolvimento para acesso às listagens.

• Usuários atuais:siga as etapas abaixo para migrar para o uso de listagens.

Observação: se você já é cliente, não é necessário migrar para as listagens durante a prévia. No entanto, quando o Insights de Lugares for lançado para GA, ele só vai oferecer suporte a listagens.

Etapas da migração

Para migrar para as listagens, você precisa:

1. Assinar as listagens da cidade e do país escolhidos. Para instruções, consulte Configurar o Places Insights.

   Observação: ao configurar o Places Insights, defina o nome do conjunto de dados para usar sua própria convenção de nomenclatura. Se você deixar o nome do conjunto de dados padrão, ele vai entrar em conflito com o nome da data clean room legada.

2. Atualize o nome do conjunto de dados nas consultas ou funções para o nome do conjunto de dados escolhido acima.

3. Se você usou funções, remova o nome do projeto usado com data clean rooms (maps-platform-analytics-hub).

4. Modifique as consultas ou funções atuais para incluir o nome do projeto (opcional) e os novos campos de endereço.

Incluir o nome do projeto ao referenciar as informações do produto (opcional)

Com as listagens, é possível incluir o nome do projeto na consulta. Se você não especificar um nome de projeto, a consulta será definida como padrão para o projeto ativo.

Talvez você queira incluir o nome do projeto se tiver conjuntos de dados vinculados com o mesmo nome em projetos diferentes ou se estiver consultando uma tabela fora do projeto ativo.

Exemplo de consulta atualizada com nome do projeto e do conjunto de dados

Esta consulta inclui um nome de projeto e usa o nome do conjunto de dados my_dataset_name:

SELECT WITH AGGREGATION_THRESHOLD
COUNT(*) AS count
FROM `PROJECT_NAME.my_dataset_name.places`

Migrar para os novos campos de endereço

Na versão inicial do Insights de Lugares, o esquema do conjunto de dados representava um campo de endereço como um STRUCT ou RECORD que continha um subcampo id e name. Essa versão simplifica o esquema para definir campos separados de nível superior para id e name. Os novos campos são de string ou matriz de strings.

Observação: para aproveitar os novos campos de endereço, é necessário migrar das data clean rooms para as listagens. Se você decidir não migrar para as listagens, continue usando os campos de endereço da versão inicial.

Por exemplo, o esquema do componente de endereço de localidade para a versão inicial é mostrado abaixo:

locality		STRUCT
	locality.id	STRING
	locality.name	STRING

Nesta versão, o conjunto de dados agora contém dois campos de matriz de strings de nível superior. Por exemplo, o esquema de dados de localidade atualizado é mostrado abaixo:

locality_ids	ARRAY<string>
locality_names	ARRAY<string>

Consulte a referência completa do esquema.

**Observação** :nem todos os campos estão disponíveis em todos os países. Para conferir a lista específica de campos disponíveis para seu país, consulte a referência de esquema específica do país.

Campos não matriciais

Nesta versão, os campos id e name agora são campos STRING de nível superior para campos de endereço não matriciais:

administrative_area_level_1_id	STRING
administrative_area_level_1_name	STRING

Esse novo formato se aplica a todos os campos no formulário administrative_area_level_N, em que N é de 1 a 7.

Observação: nem todos os campos administrative_area_level_N estão disponíveis em todos os países. Para conferir a lista específica de campos disponíveis para seu país, consulte a referência de esquema específica do país.

Exemplo de uso de novos campos

Na versão inicial do Insights de Lugares, você usou o campo administrative_area_level_1.name em uma cláusula WHERE para filtrar os resultados:

SELECT WITH AGGREGATION_THRESHOLD
COUNT(*) AS count
FROM `PROJECT_NAME.places_insights___us.places`
WHERE administrative_area_level_1.name = "New York";

Com os novos campos, você escreve a consulta usando o campo administrative_area_level_1_name:

SELECT WITH AGGREGATION_THRESHOLD
COUNT(*) AS count
FROM `PROJECT_NAME.places_insights___us.places`
WHERE administrative_area_level_1_name = "New York";