Funções personalizadas do PlaidXL
O PlaidXL acrescenta 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 lista-as, com uma breve descrição de cada argumento.
| 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 um relatório |
| Valores | CELL, CELLS |
Calcular um valor agregado para qualquer combinação de nós |
| 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 pormenorização que CELL, CELLS e DRILL utilizam |
Criar um relatório com funções personalizadas mostra estas funções a trabalhar em conjunto.
Como funcionam as funções
Seção intitulada “Como funcionam as funções”- Inicie primeiro sessão. As funções leem com o seu início de sessão no PlaidCloud, por isso inicie sessão a partir do painel de tarefas antes de as utilizar.
- Leem do projeto selecionado. Todas as funções leem do projeto selecionado no painel de tarefas.
GET_TABLE,TBL_LISTeDIM_LISTtambém aceitam um ID de projeto opcional, para ler outro projeto sem alterar a seleção. A seleção é partilhada por todos os livros que tenha abertos. - 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!. - Volte a calcular para obter as alterações. Uma fórmula PlaidXL volta a obter os dados quando um dos seus argumentos muda. Para obter novos dados no PlaidCloud, ou um projeto diferente selecionado no painel de tarefas, force um novo cálculo completo — no Windows, prima Ctrl+Alt+F9. Refresh All Tables atualiza as tabelas obtidas, não as fórmulas.
- Utilize nomes exatos. Escreva os nomes das 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. A 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. A predefinição é o projeto selecionado no painel de tarefas.horizontal—TRUEpara listar ao longo de uma linha. A 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. A predefinição é o projeto selecionado no painel de tarefas.horizontal—TRUEpara listar ao longo de uma linha. A 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 são devolvidos como células em branco.
table_name— o nome da tabela no PlaidCloud.project_id— o projeto a ler. A predefinição é o projeto selecionado no painel de tarefas.limit— o número máximo de linhas a devolver. A 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, começando em start_node e descendo pelos seus descendentes. Cada geração é indentada mais quatro espaços do que a anterior, e os grupos de estrutura do Excel permitem recolher e expandir cada nível.
dimension_name— o nome da dimensão ou o respetivo caminho no projeto.start_node— o nó de partida, como a raiz da dimensão.hierarchy— a hierarquia alternativa a seguir. A 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])
Devolve start_node e os nós abaixo dele que drill_key indicar, ao longo de uma coluna, indentados por geração e agrupados numa estrutura do Excel.
dimension_name— o nome da dimensão ou o respetivo caminho no projeto.start_node— o nó a partir do qual se percorre.drill_key— até que profundidade percorrer, a partir deDRILL_KEY: todos os descendentes, apenas as folhas ou um número de níveis.hierarchy— a hierarquia alternativa a seguir. A predefinição é"main".
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 pormenorização do friso fazem o mesmo para uma dimensão e um nó que tenha escrito em duas células, sem escrever uma fórmula.
Valores
Seção intitulada “Valores”CELL e CELLS calculam uma medida — uma coluna numérica de uma tabela — agregada aos nós que escolher numa ou mais dimensões. Pense em cada chamada como uma interseção de um relatório: a Receita de EMEA em FY2026.
A interseção descreve-se 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 um |
| A coluna a agregar | MEASURE para CELL, MEASURES ou várias células MEASURE para CELLS |
Sim |
| Como agregá-la | 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 é agregado a esse nó na hierarquia principal da dimensão — numa coluna Region associada a uma dimensão geográfica, 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 usam uma tabela cujas colunas Region e Period estão associadas a dimensões. Utilize os nomes das colunas da sua própria tabela.
=PLAIDXL.CELL(table, measure, [measure_type], node, [node], ...)
Devolve um número: a medida, agregada sobre as linhas que se encontram abaixo de todos os nós que passar.
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.
=PLAIDXL.CELLS(table, measures, [measure_type], node, [node], ...)
Como CELL, mas para várias medidas em simultâneo. Devolve um número por medida, ao longo de uma coluna, pela ordem em que as listou.
D1:F1 revenue | cost | unitsD2 =PLAIDXL.REPR.MEASURES(D1:F1)B2 =PLAIDXL.CELLS(A1, D2#, A3, A4, A5)D2# passa o resultado expandido completo de MEASURES. B2:B4 mostram a receita, o custo e as unidades de EMEA em FY2026.
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 que CELL e CELLS leem, pelo respetivo 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 medidas 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 valores, 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 mediano |
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)
Um filtro para CELL e CELLS. 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 esteja 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.
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 apontá-la 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é que profundidade DRILL desce abaixo do nó de partida. d_key é texto simples:
d_key |
Percorre até |
|---|---|
"all" |
Todos os descendentes |
"leaves" |
Apenas as folhas — nós sem nada abaixo |
"1 level", "2 levels", … |
Esse número de gerações abaixo |
Escreva o número em algarismos: "2 levels", não "two levels". Um drill inicial é ignorado, pelo que "drill 2 levels" também funciona.
Com dois ou mais níveis, DRILL lista uma geração de cada vez — todos os filhos, depois todos os netos — em vez de cada nó diretamente abaixo do respetivo nó superior. Para uma disposição aninhada, use "all" ou GET_DIMENSION com um generation_limit.
Ver também
Seção intitulada “Ver também”- Criar um relatório com funções personalizadas — uma hierarquia ao longo do lado, valores ao longo do topo
- Trabalhar com tabelas e dimensões — escolha o projeto de que as funções leem
- Utilizar dimensões — hierarquias principal e alternativas, e como os nós são agregados
- Conceber uma hierarquia da dimensão — crie a hierarquia na qual o seu relatório é agregado