Pular para o conteúdo principal
Para que as funções abaixo funcionem, a configuração do servidor deve especificar os caminhos e endereços usados para obter todos os dicionários incorporados. Os dicionários são carregados na primeira chamada de qualquer uma dessas funções. Se as listas de referência não puderem ser carregadas, será gerada uma exceção.Por isso, os exemplos mostrados nesta seção gerarão uma exceção no ClickHouse Fiddle e, por padrão, em implantações quick release e de produção, a menos que sejam previamente configurados.
Para obter informações sobre como criar listas de referência, consulte a seção “Dicionário”.

​
Múltiplas geobases

O ClickHouse suporta o uso simultâneo de múltiplas geobases alternativas (hierarquias regionais), para contemplar diferentes perspectivas sobre a quais países determinadas regiões pertencem. A configuração do ‘clickhouse-server’ especifica o arquivo com a hierarquia regional: <path_to_regions_hierarchy_file>/opt/geo/regions_hierarchy.txt</path_to_regions_hierarchy_file> Além desse arquivo, ele também procura arquivos próximos que tenham o símbolo _ e qualquer sufixo anexado ao nome (antes da extensão do arquivo). Por exemplo, ele também encontrará o arquivo /opt/geo/regions_hierarchy_ua.txt, se estiver presente. Aqui, ua é chamado de chave do dicionário. Para um dicionário sem sufixo, a chave é uma string vazia. Todos os dicionários são recarregados em tempo de execução (uma vez a cada certo número de segundos, conforme definido no parâmetro de configuração builtin_dictionaries_reload_interval, ou uma vez por hora, por padrão). No entanto, a lista de dicionários disponíveis é definida apenas uma vez, quando o servidor é iniciado. Todas as funções para trabalhar com regiões têm um argumento opcional no final — a chave do dicionário. Ela é chamada de geobase. Exemplo:

​
regionToName

Aceita um ID de região e a geobase e retorna uma string com o nome da região no idioma correspondente. Se a região com o ID especificado não existir, será retornada uma string vazia. Sintaxe
Parâmetros Valor retornado
  • Nome da região no idioma correspondente especificado por geobase. String.
  • Caso contrário, uma string vazia.
Exemplo
Query
Response

​
regionToCity

Aceita um ID de região da geobase. Se essa região for uma cidade ou parte de uma cidade, retorna o ID da região correspondente à cidade. Caso contrário, retorna 0. Sintaxe
Parâmetros Valor retornado
  • ID da região da cidade correspondente, se existir. UInt32.
  • 0, caso não exista.
Exemplo
Query
Response

​
regionToArea

Converte uma região em uma área (tipo 5 na geobase). Em todos os demais aspectos, esta função é igual a ‘regionToCity’. Sintaxe
Parâmetros Valor retornado
  • ID da região da área correspondente, se existir. UInt32.
  • 0, se não houver.
Exemplo
Query
Response

​
regionToDistrict

Converte uma região em um distrito federal (tipo 4 na geobase). Nos demais aspectos, esta função é igual a ‘regionToCity’. Sintaxe
Parâmetros Valor retornado
  • ID da região da cidade correspondente, se existir. UInt32.
  • 0, se não existir.
Exemplo
Query
Response

​
regionToCountry

Converte uma região em um país (tipo 3 na geobase). Em todos os demais aspectos, esta função é igual a ‘regionToCity’. Sintaxe
Parâmetros Valor retornado
  • ID da região do país correspondente, se existir. UInt32.
  • 0, se não houver.
Exemplo
Query
Response

​
regionToContinent

Converte uma região em um continente (tipo 1 na geobase). Em todos os demais aspectos, esta função é igual a ‘regionToCity’. Sintaxe
Parâmetros Valor retornado
  • ID da região do continente correspondente, se existir. UInt32.
  • 0, se não houver.
Exemplo
Query
Response

​
regionToTopContinent

Encontra o continente de nível mais alto na hierarquia da região. Sintaxe
Parâmetros Valor retornado
  • Identificador do continente de nível mais alto (o último ao subir na hierarquia de regiões). UInt32.
  • 0, se não houver.
Exemplo
Query
Response

​
regionToPopulation

Obtém a população de uma região. A população pode estar registrada em arquivos da geobase. Consulte a seção “Dicionários”. Se a população não estiver registrada para a região, retorna 0. Na geobase, a população pode estar registrada para regiões filhas, mas não para a região pai. Sintaxe
Parâmetros Valor retornado
  • População da região. UInt32.
  • 0, caso não exista.
Exemplo
Query
Response

​
regionIn

Verifica se uma região lhs pertence à região rhs. Retorna um número UInt8 igual a 1 se pertencer, ou 0 se não pertencer. Sintaxe
Parâmetros Valor retornado
  • 1, se pertencer. UInt8.
  • 0, se não pertencer.
Detalhes de implementação A relação é reflexiva — toda região também pertence a si mesma. Exemplo
Query
Response

​
regionHierarchy

Aceita um número UInt32 — o ID da região na geobase. Retorna um array de IDs de região composto pela região informada e por todas as regiões pai na hierarquia. Sintaxe
Parâmetros Valor retornado
  • Array de IDs de região composto pela região informada e por todas as regiões pai ao longo da cadeia. Array(UInt32).
Exemplo
Query
Response
Última modificação em 3 de julho de 2026