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.
Como funcionam as funções
Seção intitulada “Como funcionam as funções”- 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_LISTeDIM_LISTtambé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.
LIST_PROJECTS
Seção intitulada “LIST_PROJECTS”=PLAIDXL.LIST_PROJECTS([horizontal])
Lista os nomes dos projetos que pode abrir, ordenados por nome.
horizontal—TRUEpara listar ao longo de uma linha. Por predefinição éFALSE, uma coluna.
TBL_LIST
Seção intitulada “TBL_LIST”=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—TRUEpara listar ao longo de uma linha. Por predefinição éFALSE, uma coluna.
GET_COLUMNS
Seção intitulada “GET_COLUMNS”=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.
DIM_LIST
Seção intitulada “DIM_LIST”=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—TRUEpara listar ao longo de uma linha. Por predefinição éFALSE, uma coluna.
Tabelas
Seção intitulada “Tabelas”GET_TABLE
Seção intitulada “GET_TABLE”=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.
Hierarquias
Seção intitulada “Hierarquias”GET_DIMENSION
Seção intitulada “GET_DIMENSION”=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, contandostart_nodecomo a primeira:2devolve 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 deDRILL_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 quedrill_keypede: 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.
Valores
Seção intitulada “Valores”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 | unitsD2 =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.
Indicadores
Seção intitulada “Indicadores”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 filtroDIMENSION_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.
METRIC_BREAKDOWN
Seção intitulada “METRIC_BREAKDOWN”=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 filtroDIMENSION_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.
Erros de indicadores
Seção intitulada “Erros de indicadores”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. |
Blocos de construção
Seção intitulada “Blocos de construção”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.
TABLE_REPR
Seção intitulada “TABLE_REPR”=PLAIDXL.REPR.TABLE_REPR(table_name)
A tabela de onde CELL e CELLS leem, pelo nome no projeto selecionado.
MEASURE
Seção intitulada “MEASURE”=PLAIDXL.REPR.MEASURE(column_name)
A coluna numérica que CELL agrega.
MEASURES
Seção intitulada “MEASURES”=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#.
MEASURE_TYPE
Seção intitulada “MEASURE_TYPE”=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 |
DIMENSION_REPR
Seção intitulada “DIMENSION_REPR”=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.
DRILL_KEY
Seção intitulada “DRILL_KEY”=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.
Inserir um indicador
Seção intitulada “Inserir um indicador”Clique em Metric… no grupo Inserir do friso ou escolha A business metric no separador Formulas.
- 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. - Utilize as teclas de seta ou clique para escolher um indicador.
- Opcionalmente, adicione filtros: escolha uma Dimensão, escreva um Nó e clique em Adicionar filtro.
- Opcionalmente, escolha uma coluna em Breakdown by (optional) para escrever
METRIC_BREAKDOWNem vez de um único número. - Clique em Insert in active cell ou em Copiar.
Relacionado
Seção intitulada “Relacionado”- Criar um relatório — uma hierarquia ao longo do lado, valores ao longo do topo
- Trabalhar com tabelas e dimensões — escolha o projeto de onde as funções leem
- Utilizar dimensões — hierarquias principal e alternativas, e como os nós se agregam
- Conceber uma hierarquia de dimensão — construa a hierarquia na qual o seu relatório se agrega