Pular para o conteúdo

Funções personalizadas do PlaidXL

O PlaidXL adiciona ao Excel funções que leem dados do PlaidCloud diretamente para as células. Escreva =PLAIDXL. numa célula e o preenchimento automático do Excel apresenta-as, com uma breve descrição de cada argumento. O separador Formulas do painel de tarefas também pode escrever uma por si; consulte Inserir uma fórmula a partir do painel de tarefas.

Grupo Funções Utilize-as para
Listas LIST_PROJECTS, TABLE.TBL_LIST, TABLE.GET_COLUMNS, DIMENSION.DIM_LIST Ver o que está disponível para construir
Tabelas TABLE.GET_TABLE Ler uma tabela inteira para um intervalo
Hierarquias DIMENSION.GET_DIMENSION, DRILL Dispor os nós de uma dimensão como linhas de relatório
Valores CELL, CELLS Calcular um valor agregado para qualquer combinação de nós
Indicadores METRIC, METRIC_BREAKDOWN Ler um indicador de negócio governado, tal como os painéis de controlo o mostram
Blocos de construção REPR.TABLE_REPR, REPR.MEASURE, REPR.MEASURES, REPR.MEASURE_TYPE, REPR.DIMENSION_REPR, REPR.DRILL_KEY Descrever a tabela, a medida, a agregação, os nós e a profundidade de exploração que CELL, CELLS e DRILL utilizam

Criar um relatório mostra estas funções a trabalhar em conjunto.

  • Inicie sessão primeiro. As funções leem com o seu início de sessão no PlaidCloud e as suas permissões, pelo que deve iniciar sessão a partir do painel de tarefas antes de as utilizar.
  • Leem a partir do projeto do livro. Cada função lê a partir do projeto associado ao livro no painel de tarefas. GET_TABLE, TBL_LIST e DIM_LIST também aceitam um ID de projeto opcional, para ler outro projeto sem alterar a associação. Cada livro tem o seu próprio projeto, pelo que dois livros abertos podem ler de projetos diferentes.
  • Os resultados expandem-se. Uma função que devolve uma lista ou uma tabela preenche as células abaixo (ou à direita). Deixe espaço para os resultados; se algo estiver no caminho, o Excel mostra um erro #SPILL!.
  • Recalcule para obter as alterações. Uma fórmula do PlaidXL volta a obter os dados quando um dos seus argumentos muda. Para obter dados novos no PlaidCloud, ou um projeto diferente associado no painel de tarefas, utilize o menu Atualizar do friso: Recalculate PlaidXL formulas recalcula todas as fórmulas do PlaidXL no livro, e Refresh this sheet e Refresh selection recalculam as fórmulas que abrangem. Refresh all tables atualiza as tabelas obtidas, não as fórmulas. Consulte Atualizar.
  • Utilize nomes exatos. Escreva os nomes de tabelas, colunas, dimensões e nós exatamente como aparecem no PlaidCloud.

Os argumentos entre parênteses retos são opcionais.

=PLAIDXL.LIST_PROJECTS([horizontal])

Lista os nomes dos projetos que pode abrir, ordenados por nome.

  • horizontal — TRUE para listar ao longo de uma linha. Por predefinição é FALSE, uma coluna.

=PLAIDXL.TABLE.TBL_LIST([project_id], [horizontal])

Lista os nomes das tabelas de um projeto, ordenados por nome.

  • project_id — o projeto a ler. Por predefinição é o projeto do livro.
  • horizontal — TRUE para listar ao longo de uma linha. Por predefinição é FALSE, uma coluna.

=PLAIDXL.TABLE.GET_COLUMNS(table_name, [column_filter], [orientation])

Lista os nomes das colunas de uma tabela do projeto selecionado.

  • table_name — o nome da tabela no PlaidCloud.
  • column_filter — um tipo de dados, como "text", para listar apenas as colunas desse tipo. Omita-o para listar todas as colunas.
  • orientation — "vertical" (a predefinição) para uma coluna, ou "horizontal" para uma linha.

=PLAIDXL.DIMENSION.DIM_LIST([project_id], [horizontal])

Lista os nomes das dimensões de um projeto.

  • project_id — o projeto a ler. Por predefinição é o projeto do livro.
  • horizontal — TRUE para listar ao longo de uma linha. Por predefinição é FALSE, uma coluna.

=PLAIDXL.TABLE.GET_TABLE(table_name, [project_id], [limit])

Devolve as linhas de uma tabela com uma linha de cabeçalho, expandidas a partir da célula da fórmula. Os valores vazios voltam como células em branco.

  • table_name — o nome da tabela no PlaidCloud.
  • project_id — o projeto a ler. Por predefinição é o projeto do livro.
  • limit — o número máximo de linhas a devolver. Por predefinição é 1 048 575, o máximo que uma folha de cálculo comporta abaixo de uma linha de cabeçalho.

GET_TABLE devolve todas as colunas. Para escolher colunas ou filtrar linhas, obtenha antes a tabela a partir do painel de tarefas.

=PLAIDXL.DIMENSION.GET_DIMENSION(dimension_name, start_node, [hierarchy], [orientation], [generation_limit])

Dispõe os nós de uma dimensão, a partir de start_node e descendo pelos seus descendentes. Cada geração é indentada quatro espaços mais do que a anterior, e os grupos de estrutura de tópicos do Excel permitem-lhe recolher e expandir cada nível.

  • dimension_name — o nome da dimensão ou o seu caminho no projeto.
  • start_node — o nó de partida, como a raiz da dimensão.
  • hierarchy — a hierarquia alternativa a seguir. Por predefinição é "main".
  • orientation — "vertical" (a predefinição) para listar os nós ao longo de uma coluna, ou "horizontal" para os listar ao longo de uma linha.
  • generation_limit — quantas gerações devolver, contando start_node como a primeira: 2 devolve o nó de partida e os seus filhos. Omita-o para devolver todas as gerações.

=PLAIDXL.DRILL(dimension_name, start_node, drill_key, [hierarchy], [exclude], [expand], [orientation])

Devolve start_node e os nós abaixo dele que drill_key pede, indentados por geração e agrupados numa estrutura de tópicos do Excel.

  • dimension_name — o nome da dimensão ou o seu caminho no projeto.
  • start_node — o nó a partir do qual explorar. Deixe-o vazio ("") para começar pelos nós de topo da dimensão. A própria dimensão conta como geração 0 da chave de exploração e não é listada, pelo que os nós de topo são a geração 1: >[1] lista apenas os nós de topo e >[0] não lista nada.
  • drill_key — até onde explorar, a partir de DRILL_KEY: todos os descendentes, apenas as folhas, um número de níveis ou um intervalo de gerações.
  • hierarchy — a hierarquia alternativa a seguir. Por predefinição é "main".
  • exclude — nós a deixar de fora, com tudo o que está abaixo deles: um nó, uma lista ou um intervalo de células. O nó de partida nunca é deixado de fora.
  • expand — nós cujos filhos devem ser mostrados também, mesmo abaixo da profundidade que drill_key pede: um nó, uma lista ou um intervalo de células. Apenas os nós que a exploração mostra são abertos, pelo que, para abrir um neto, indique também o respetivo pai.
  • orientation — "vertical" (a predefinição) para listar os nós ao longo de uma coluna, ou "horizontal" para os listar ao longo de uma linha, sem indentação e agrupados por coluna. Qualquer outro valor é um erro.

exclude e expand aceitam IDs de nós como texto ou números; as células vazias e os erros num intervalo são ignorados. Deixe um argumento vazio ("") para o omitir, como em =PLAIDXL.DRILL("Period", "FY2026", PLAIDXL.REPR.DRILL_KEY("1 level"), "main", "", "", "horizontal").

Por exemplo, =PLAIDXL.DRILL("Region", "Total", PLAIDXL.REPR.DRILL_KEY("leaves")) lista Total seguido de todas as regiões-folha abaixo dele.

Os comandos de exploração escrevem e editam fórmulas DRILL por si: selecione um nó e explore para baixo, explore para cima, mantenha ou remova nós.

CELL e CELLS calculam uma medida — uma coluna numérica de uma tabela — agregada para os nós que escolher numa ou mais dimensões. Pense em cada chamada como uma interseção num relatório: Receita de EMEA em FY2026.

Descreve-se a interseção com as funções de blocos de construção abaixo, normalmente nas suas próprias células, e depois passam-se essas células a CELL ou CELLS por qualquer ordem:

Argumento Construído com Obrigatório
A tabela a ler TABLE_REPR Exatamente uma
A coluna a agregar MEASURE para CELL, MEASURES ou várias células MEASURE para CELLS Sim
Como a agregar MEASURE_TYPE Não — a predefinição é sum
Um filtro numa coluna DIMENSION_REPR Pelo menos um, um por coluna

Cada filtro indica uma coluna da tabela e um valor. Quando essa coluna está associada a uma dimensão no PlaidCloud, o valor é um nó e o filtro inclui tudo o que se agrega nesse nó na hierarquia principal da dimensão, ou na hierarquia que indicar — numa coluna Region associada a uma dimensão de geografia, o nó EMEA abrange todos os países abaixo dele. Numa coluna que não está associada a uma dimensão, o filtro corresponde exatamente ao valor.

Os exemplos desta página utilizam uma tabela cujas colunas Region e Period estão associadas a dimensões. Utilize os nomes de colunas da sua própria tabela.

=PLAIDXL.CELL(table, measure, [measure_type], node, [node], ...)

Devolve um número: a medida, agregada nas linhas que se enquadram em todos os nós indicados.

A1 =PLAIDXL.REPR.TABLE_REPR("Sales")
A2 =PLAIDXL.REPR.MEASURE("revenue")
A3 =PLAIDXL.REPR.MEASURE_TYPE("sum")
A4 =PLAIDXL.REPR.DIMENSION_REPR("Region", "EMEA")
A5 =PLAIDXL.REPR.DIMENSION_REPR("Period", "FY2026")
B1 =PLAIDXL.CELL(A1, A2, A3, A4, A5)

B1 mostra a receita total de EMEA em FY2026.

Escreva um número sobre um CELL para o gravar no PlaidCloud. Consulte Escrever valores no PlaidCloud.

Uma folha cheia de fórmulas CELL calcula rapidamente: as fórmulas CELL que calculam em conjunto são enviadas ao PlaidCloud num único pedido, até 10 000 de cada vez, e o PlaidXL reutiliza os detalhes das colunas de uma tabela durante 30 segundos em vez de os obter para cada célula. Se não for possível calcular um valor, a célula mostra #VALUE! e, ao passar o rato sobre ela, o motivo é apresentado tal como o PlaidCloud o comunicou, como uma coluna de filtro que não está na tabela ou um nó sem membros. CELLS mostra o primeiro motivo para todo o resultado.

Quando nenhuma linha corresponde, um sum é 0. Qualquer outra forma de combinar (mean, median, min, max, std ou var) não tem valor para dar: um CELL mostra #VALUE! com No value for a agregação, os membros e a medida ao passar o rato, e um elemento de CELLS fica em branco. As funções do Excel como AVERAGE ignoram um elemento em branco de CELLS, e Explicar dá o mesmo motivo.

=PLAIDXL.CELLS(table, measures, [measure_type], node, [node], ...)

Como CELL, mas para várias medidas de uma só vez. Devolve um número por medida, ao longo de uma coluna, pela ordem em que as indicou.

D1:F1 revenue | cost | units
D2 =PLAIDXL.REPR.MEASURES(D1:F1)
B2 =PLAIDXL.CELLS(A1, D2#, A3, A4, A5)

D2# passa todo o resultado expandido de MEASURES. B2:B4 mostram a receita, o custo e as unidades de EMEA em FY2026.

METRIC e METRIC_BREAKDOWN leem uma definição de indicador do projeto do livro: um número de negócio como Net Revenue cujo cálculo está acordado e documentado no PlaidCloud. O valor é o que os painéis de controlo mostram, calculado com o seu próprio acesso a linhas. Metric… no friso lista os indicadores do projeto com os seus valores atuais e escreve a fórmula por si; consulte Inserir um indicador.

Os filtros são valores de DIMENSION_REPR, tal como para CELL, exceto que o primeiro argumento indica uma coluna pela qual o indicador pode ser desagregado. Um nó inclui tudo o que está abaixo dele. Passe um único filtro ou um intervalo ou lista deles; os filtros vazios são ignorados. Uma fórmula pode utilizar filtros de mais do que uma hierarquia alternativa e pode combinar um membro de uma hierarquia alternativa com membros de outras dimensões.

=PLAIDXL.METRIC(name, [filter], ...)

Devolve um número: o indicador, para as linhas sob todos os filtros indicados.

  • name — o nome do indicador, um dos seus sinónimos ou o seu ID. A distinção entre maiúsculas e minúsculas não é relevante.
  • filter — um filtro DIMENSION_REPR. Indique quantos necessitar.
=PLAIDXL.METRIC("Net Revenue", PLAIDXL.REPR.DIMENSION_REPR("Region", "EMEA"))

Quando nenhuma linha corresponde, METRIC devolve 0; quando o indicador não tem valor, a célula fica em branco.

=PLAIDXL.METRIC_BREAKDOWN(name, breakdown, [filter], ...)

Devolve o indicador repartido por uma coluna: duas colunas, com cada membro de breakdown ao lado do seu valor, do maior valor para o menor, sem linha de cabeçalho.

  • name — o nome do indicador, um dos seus sinónimos ou o seu ID.
  • breakdown — a coluna pela qual repartir o indicador, uma pela qual o indicador possa ser desagregado.
  • filter — um filtro DIMENSION_REPR. Indique quantos necessitar.
=PLAIDXL.METRIC_BREAKDOWN("Net Revenue", "Region")

Os membros sem valor ficam no fim, com um valor em branco. Quando nenhuma linha corresponde, devolve uma linha: um membro vazio e 0.

Um indicador que não pode ser calculado mostra #VALUE!; passe o rato sobre a célula para ver o motivo:

Mensagem O que fazer
Indicador desconhecido ou coluna desconhecida Verifique o nome. Quando existem correspondências próximas, a mensagem lista-as a seguir a Did you mean.
O nome corresponde a mais do que um indicador Utilize o nome completo do indicador ou o seu ID.
Your PlaidCloud role doesn’t allow reading metrics in this project. Peça acesso a um proprietário do projeto.
This PlaidCloud workspace doesn’t serve metrics to Excel yet. Peça ao seu administrador que atualize a área de trabalho.
PlaidCloud is busy; try again in um número de segundos O PlaidXL já tentou novamente. Recalcule depois do tempo indicado.
Choose a project in the PlaidXL pane first. Associe o livro a um projeto.
This PlaidCloud workspace can’t combine an alternate hierarchy with other members yet. Ask your administrator to update the workspace. Peça ao administrador que atualize a área de trabalho. As outras células do mesmo recálculo continuam a responder.

Estas funções não leem dados por si próprias. Cada uma devolve um pequeno excerto de texto que descreve uma parte de um cálculo, pronto a passar a CELL, CELLS ou DRILL. Coloque-as em células que referencia, para que uma única alteração — um período diferente, por exemplo — atualize todas as fórmulas que as utilizam.

=PLAIDXL.REPR.TABLE_REPR(table_name)

A tabela de onde CELL e CELLS leem, pelo nome no projeto selecionado.

=PLAIDXL.REPR.MEASURE(column_name)

A coluna numérica que CELL agrega.

=PLAIDXL.REPR.MEASURES(column_names)

Várias colunas de medida para CELLS, a partir de um intervalo de células que contêm nomes de colunas. O resultado expande-se numa célula por coluna; passe-o a CELLS com o operador de expansão, como D2#.

=PLAIDXL.REPR.MEASURE_TYPE(agg_function)

Como agregar a medida. agg_function é um dos seguintes, em minúsculas:

Valor Devolve
sum O total (a predefinição quando não passa um tipo de medida)
mean A média
median O valor central
min O menor valor
max O maior valor
std O desvio-padrão
var A variância

=PLAIDXL.REPR.DIMENSION_REPR(dimension_name, start_node, [hierarchy])

Um filtro para CELL, CELLS, METRIC e METRIC_BREAKDOWN. Passe um por cada coluna pela qual pretende filtrar.

  • dimension_name — o nome de uma coluna da tabela — a coluna que contém os valores da dimensão, como "Region". Tem de corresponder exatamente ao nome da coluna; uma coluna que não está na tabela devolve um erro.
  • start_node — o nó até ao qual agregar, como "EMEA". Numa coluna que não está associada a uma dimensão, o valor a corresponder.
  • hierarchy — a hierarquia alternativa pela qual agregar o nó. Por predefinição é "main".

Referencie uma célula para o nó para construir uma grelha: =PLAIDXL.REPR.DIMENSION_REPR("Region", $A7). Os espaços iniciais e finais são ignorados, pelo que pode apontar para os nomes de nós indentados que DRILL dispõe.

=PLAIDXL.REPR.DRILL_KEY(d_key)

Até onde DRILL vai abaixo do nó de partida. d_key é texto simples, seja uma forma em palavras ou uma chave de exploração escrita por extenso:

d_key Explora até
"all" Todos os descendentes
"leaves" Apenas as folhas, que são os nós sem nada abaixo
"1 level", "2 levels", … Esse número de gerações para baixo
">[...]" A chave de exploração escrita por extenso, como na tabela seguinte

Escreva o número em algarismos: "2 levels", não "two levels". Um drill inicial é ignorado, pelo que "drill 2 levels" também funciona.

Uma chave escrita por extenso conta as gerações para baixo a partir do nó de partida, que é a geração 0 e está sempre incluído. Os números negativos contam para cima a partir das folhas de cada ramo, pelo que uma hierarquia irregular funciona como seria de esperar.

Chave Inclui
>[*] ou >[:] Todos os nós
>[] ou >[-1] Apenas as folhas
>[n] O nó de partida e n gerações abaixo dele. >[0] é apenas o nó de partida.
>[a:] O nó de partida, depois a geração a e tudo o que está abaixo dela
>[a:b] O nó de partida, depois as gerações de a até b - 1
>[0:-k] O nó de partida e todos os nós que têm pelo menos k gerações abaixo, pelo que as últimas k gerações de cada ramo ficam de fora. >[0:-1] é todos os nós exceto as folhas.
>[a:-k] O mesmo, começando na geração a

Para a hierarquia A, com os filhos B, C e D, em que B tem B1 e B2 e C tem C1:

Chave Resultado
>[1] A, B, C, D
>[2] A, B, B1, B2, C, C1, D
>[] A, B1, B2, C1, D
>[0:-1] A, B, C
>[2:] A, B1, B2, C1

Os nós são listados pela ordem da hierarquia, cada um sob o seu próprio pai, e os grupos de estrutura de tópicos do Excel seguem a mesma ordem. Os espaços dentro de uma chave são ignorados. Uma chave que não corresponda a nenhuma destas formas devolve um erro que lista as formas válidas.

Inserir uma fórmula a partir do painel de tarefas

Seção intitulada “Inserir uma fórmula a partir do painel de tarefas”

O separador Formulas do painel de tarefas escreve uma fórmula por si. Abra-o a partir do painel de tarefas, com Formula… no friso ou com Insert formula here… no menu de contexto PlaidXL. Em What do you want in the cell?, escolha uma opção:

  • A whole table (GET_TABLE) — escolha ou escreva a tabela e, opcionalmente, um número máximo de linhas.
  • One number (CELL) — escolha ou escreva a tabela, escolha a Column to total e How to combine the values.
  • A list of dimension nodes (DRILL) — escolha ou escreva a dimensão e o nó de partida, escolha até onde explorar e, opcionalmente, uma Hierarquia alternativa, nós a excluir e nós a abrir. Linhas mostra uma pré-visualização dos nós que a exploração lista. Consulte Exploração personalizada.
  • A business metric (METRIC) — consulte Inserir um indicador.

A pré-visualização Formula mostra o resultado à medida que preenche os campos. Clique em Insert in active cell (ou prima Ctrl+Enter) para o colocar na célula selecionada, ou em Copiar para o colar por si. Escolher uma tabela no separador Tabelas ou uma dimensão no separador Dimensões preenche o campo correspondente.

Clique em Metric… no grupo Inserir do friso ou escolha A business metric no separador Formulas.

  1. Em Metric, escreva parte do nome ou do sinónimo de um indicador, como revenue. Cada correspondência mostra o seu valor atual e descrição.
  2. Utilize as teclas de seta ou clique para escolher um indicador.
  3. Opcionalmente, adicione filtros: escolha uma Dimensão, escreva um Nó e clique em Adicionar filtro.
  4. Opcionalmente, escolha uma coluna em Breakdown by (optional) para escrever METRIC_BREAKDOWN em vez de um único número.
  5. Clique em Insert in active cell ou em Copiar.