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 as informações e não precisam migrar.

A versão do Places Insights de 4 de setembro de 2025 inclui as seguintes mudanças em relação à versão inicial:

• É possível assinar o Places Insights no local do BigQuery de sua escolha.

• Move os conjuntos de dados do Places Insights das data clean rooms para anúncios da troca de dados do BigQuery.

• 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, migre para as fichas. Se você decidir não migrar para as informações de produtos e continuar usando as salas limpas de dados, use os campos de endereço e o esquema de conjunto de dados da versão inicial.

Migrar para listagens

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

Para assinar os Insights de lugares em uma região específica, é necessário assinar as novas fichas no compartilhamento do BigQuery. Depois de se inscrever nas novas fichas, não é necessário modificar suas consultas SQL. Elas vão continuar funcionando da mesma forma.

• Novos usuários:se você é um novo usuário do Places Insights, siga as etapas em Configurar o Places Insights para configurar seu ambiente de desenvolvimento para acessar as informações.

• Usuários atuais:siga as etapas abaixo para migrar e usar as informações de uso

Observação: se você já é cliente, não precisa migrar para as informações do produto durante a prévia. No entanto, quando o Places Insights estiver disponível para todos, ele vai oferecer suporte apenas a fichas.

Etapas da migração

Para migrar para as fichas da empresa, você precisa:

1. Inscreva-se nas informações 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 padrão, ele vai entrar em conflito com o nome da data clean room legada.

2. Atualize o nome do conjunto de dados nas suas consultas ou funções para o nome que você escolheu acima.

3. Se você já 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.

Inclua o nome do projeto ao fazer referência à página de detalhes (opcional)

Com as listagens, você pode incluir o nome do projeto na consulta. Se você não especificar um nome de projeto, a consulta vai usar o projeto ativo por padrão.

Inclua o nome do projeto se você 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

Essa 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 Places Insights, o esquema do conjunto de dados representava um campo de endereço como um STRUCT ou RECORD que continha um subcampo id e name. Esta 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, migre das salas limpas de dados para as informações de produtos. Se você decidir não migrar para as informações de produtos, continue usando os campos de endereço da versão inicial.

Por exemplo, o esquema do componente de endereço da 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 no seu país, consulte a referência de esquema específico do país.

Campos não de matriz

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 do 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 no seu país, consulte a referência de esquema específico do país.

Exemplo usando novos campos

Na versão inicial do Places Insights, você usava 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";