Funções personalizadas do PlaidXL
O PlaidXL adiciona ao Excel funções que leem dados do PlaidCloud diretamente nas células. Digite =PLAIDXL. em uma célula e o preenchimento automático do Excel as lista, com uma breve descrição de cada argumento. A guia Formulas do painel de tarefas também pode escrever uma para você; consulte Inserir uma fórmula pelo painel de tarefas.
| Grupo | Funções | Use para |
|---|---|---|
| Listas | LIST_PROJECTS, TABLE.TBL_LIST, TABLE.GET_COLUMNS, DIMENSION.DIM_LIST |
Ver o que está disponível para usar como base |
| Tabelas | TABLE.GET_TABLE |
Ler uma tabela inteira em um intervalo |
| Hierarquias | DIMENSION.GET_DIMENSION, DRILL |
Organizar os nós de uma dimensão como linhas de relatório |
| Valores | CELL, CELLS |
Calcular um valor consolidado para qualquer combinação de nós |
| Métricas | METRIC, METRIC_BREAKDOWN |
Ler uma métrica de negócios governada, como os painéis a exibem |
| 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 detalhamento que CELL, CELLS e DRILL usam |
Criar um relatório mostra essas funções trabalhando em conjunto.
Como as funções funcionam
Seção intitulada “Como as funções funcionam”- Faça login primeiro. As funções leem com o seu login do PlaidCloud e as suas permissões; portanto, faça login pelo painel de tarefas antes de usá-las.
- Elas leem do projeto da pasta de trabalho. Toda função lê do projeto vinculado à pasta de trabalho no painel de tarefas.
GET_TABLE,TBL_LISTeDIM_LISTtambém aceitam um ID de projeto opcional, para ler outro projeto sem alterar o vínculo. Cada pasta de trabalho tem o seu próprio projeto; assim, duas pastas de trabalho abertas podem ler de projetos diferentes. - Os resultados se expandem. Uma função que retorna uma lista ou uma tabela preenche as células abaixo dela (ou à direita). Deixe espaço para os resultados; se houver algo no caminho, o Excel exibe um erro
#SPILL!. - Recalcule para obter as alterações. Uma fórmula do PlaidXL busca os dados novamente quando um de seus argumentos muda. Para obter novos dados no PlaidCloud, ou um projeto diferente vinculado no painel de tarefas, use o menu Atualizar da faixa de opções: Recalculate PlaidXL formulas recalcula todas as fórmulas do PlaidXL na pasta de trabalho, e Refresh this sheet e Refresh selection recalculam as fórmulas que abrangem. Refresh all tables atualiza as tabelas recuperadas, não as fórmulas. Consulte Atualizar.
- Use nomes exatos. Digite os nomes de tabelas, colunas, dimensões e nós exatamente como aparecem no PlaidCloud.
Os argumentos entre colchetes são opcionais.
LIST_PROJECTS
Seção intitulada “LIST_PROJECTS”=PLAIDXL.LIST_PROJECTS([horizontal])
Lista os nomes dos projetos que você pode abrir, ordenados por nome.
horizontal—TRUEpara listar ao longo de uma linha. O padrã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 ser lido. O padrão é o projeto da pasta de trabalho.horizontal—TRUEpara listar ao longo de uma linha. O padrã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 para listar todas as colunas.orientation—"vertical"(o padrã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 ser lido. O padrão é o projeto da pasta de trabalho.horizontal—TRUEpara listar ao longo de uma linha. O padrã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])
Retorna as linhas de uma tabela com uma linha de cabeçalho, expandidas a partir da célula da fórmula. Os valores vazios retornam como células em branco.
table_name— o nome da tabela no PlaidCloud.project_id— o projeto a ser lido. O padrão é o projeto da pasta de trabalho.limit— o número máximo de linhas a retornar. O padrão é 1.048.575, o máximo que uma planilha comporta abaixo de uma linha de cabeçalho.
GET_TABLE retorna todas as colunas. Para escolher colunas ou filtrar linhas, recupere a tabela pelo 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])
Organiza os nós de uma dimensão, começando em start_node e descendo pelos seus descendentes. Cada geração é recuada quatro espaços a mais que a geração pai, e os grupos de estrutura de tópicos do Excel permitem recolher e expandir cada nível.
dimension_name— o nome da dimensão ou o caminho dela no projeto.start_node— o nó de partida, como a raiz da dimensão.hierarchy— a hierarquia alternativa a seguir. O padrão é"main".orientation—"vertical"(o padrão) para listar os nós ao longo de uma coluna, ou"horizontal"para listá-los ao longo de uma linha.generation_limit— quantas gerações retornar, contandostart_nodecomo a primeira:2retorna o nó de partida e os filhos dele. Omita para retornar todas as gerações.
=PLAIDXL.DRILL(dimension_name, start_node, drill_key, [hierarchy], [exclude], [expand], [orientation])
Retorna start_node e os nós abaixo dele que drill_key solicita, recuados por geração e agrupados em uma estrutura de tópicos do Excel.
dimension_name— o nome da dimensão ou o caminho dela no projeto.start_node— o nó a partir do qual detalhar. Deixe vazio ("") para começar pelos nós de nível superior da dimensão. A própria dimensão conta como a geração 0 da chave de detalhamento e não é listada; assim, os nós de nível superior são a geração 1:>[1]lista apenas os nós de nível superior, e>[0]não lista nada.drill_key— até onde detalhar, a partir deDRILL_KEY: todos os descendentes, somente as folhas, um número de níveis ou um intervalo de gerações.hierarchy— a hierarquia alternativa a seguir. O padrão é"main".exclude— nós a omitir, com tudo o que está abaixo deles: um nó, uma lista ou um intervalo de células. O nó de partida nunca é omitido.expand— nós cujos filhos também devem ser exibidos, mesmo abaixo da profundidade quedrill_keysolicita: um nó, uma lista ou um intervalo de células. Somente os nós que o detalhamento exibe são abertos; portanto, para abrir um neto, liste também o pai dele.orientation—"vertical"(o padrão) para listar os nós ao longo de uma coluna, ou"horizontal"para listá-los ao longo de uma linha, sem recuo e agrupados por coluna. Qualquer outro valor é um erro.
exclude e expand aceitam IDs de nós como texto ou números; células vazias e erros em um intervalo são ignorados. Deixe um argumento vazio ("") para ignorá-lo, 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 detalhamento escrevem e editam fórmulas DRILL para você: selecione um nó e detalhe para baixo, detalhe 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 — consolidada nos nós que você escolher em uma ou mais dimensões. Pense em cada chamada como uma interseção em um relatório: Receita de EMEA em FY2026.
Você descreve a interseção com as funções de blocos de construção abaixo, geralmente em células próprias, e depois passa essas células para CELL ou CELLS em qualquer ordem:
| Argumento | Criado com | Obrigatório |
|---|---|---|
| A tabela a ser lida | TABLE_REPR |
Exatamente um |
| A coluna a ser agregada | MEASURE para CELL, MEASURES ou várias células MEASURE para CELLS |
Sim |
| Como agregá-la | MEASURE_TYPE |
Não — o padrão é sum |
| Um filtro em uma coluna | DIMENSION_REPR |
Pelo menos um, um por coluna |
Cada filtro nomeia uma coluna da tabela e um valor. Quando essa coluna está vinculada a uma dimensão no PlaidCloud, o valor é um nó, e o filtro inclui tudo o que se consolida nesse nó na hierarquia principal da dimensão, ou na hierarquia que você indicar — em uma coluna Região vinculada a uma dimensão de geografia, o nó EMEA abrange todos os países abaixo dele. Em uma coluna que não está vinculada a uma dimensão, o filtro corresponde exatamente ao valor.
Os exemplos desta página usam uma tabela cujas colunas Região e Período estão vinculadas a dimensões. Use os nomes das colunas da sua própria tabela.
=PLAIDXL.CELL(table, measure, [measure_type], node, [node], ...)
Retorna um número: a medida, agregada nas linhas que ficam abaixo de todos os nós que você 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.
Digite um número sobre uma CELL para gravá-lo no PlaidCloud. Consulte Digitar valores no PlaidCloud.
Uma planilha cheia de fórmulas CELL calcula rapidamente: as fórmulas CELL que são calculadas juntas são enviadas ao PlaidCloud em uma única solicitação, até 10.000 por vez, e o PlaidXL reutiliza os detalhes das colunas de uma tabela por 30 segundos em vez de buscá-los para cada célula. Se um valor não puder ser calculado, a célula exibe #VALUE! e, ao passar o mouse sobre ela, o motivo aparece como o PlaidCloud o informou, como uma coluna de filtro que não está na tabela ou um nó sem membros. CELLS mostra o primeiro motivo para o resultado inteiro.
Quando nenhuma linha corresponde, um sum é 0. Qualquer outra forma de combinação (mean, median, min, max, std ou var) não tem valor a fornecer: uma CELL exibe #VALUE! com No value for a agregação, os membros e a medida ao passar o mouse, e um elemento de CELLS fica em branco. Funções do Excel como AVERAGE ignoram um elemento em branco de CELLS, e Explicar informa o mesmo motivo.
=PLAIDXL.CELLS(table, measures, [measure_type], node, [node], ...)
Como CELL, mas para várias medidas de uma só vez. Retorna um número por medida, ao longo de uma coluna, na ordem em que você 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 inteiro de MEASURES. B2:B4 mostram receita, custo e unidades de EMEA em FY2026.
Métricas
Seção intitulada “Métricas”METRIC e METRIC_BREAKDOWN leem uma definição de métrica do projeto da pasta de trabalho: um número de negócios, como Net Revenue, cujo cálculo é acordado e registrado no PlaidCloud. O valor é o que os painéis exibem, calculado com o seu próprio acesso a linhas. Metric… na faixa de opções lista as métricas do projeto com os valores atuais e escreve a fórmula para você; consulte Inserir uma métrica.
Os filtros são valores de DIMENSION_REPR, como em CELL, exceto que o primeiro argumento nomeia uma coluna pela qual a métrica pode ser detalhada. Um nó inclui tudo o que está abaixo dele. Passe um único filtro, ou um intervalo ou lista de filtros; filtros vazios são ignorados. Uma fórmula pode usar filtros de mais de uma hierarquia alternativa e pode combinar um membro de hierarquia alternativa com membros de outras dimensões.
=PLAIDXL.METRIC(name, [filter], ...)
Retorna um número: a métrica, para as linhas abaixo de todos os filtros que você passar.
name— o nome da métrica, um de seus sinônimos ou o ID dela. Maiúsculas e minúsculas não importam.filter— um filtroDIMENSION_REPR. Passe quantos precisar.
=PLAIDXL.METRIC("Net Revenue", PLAIDXL.REPR.DIMENSION_REPR("Region", "EMEA"))Quando nenhuma linha corresponde, METRIC retorna 0; quando a métrica não tem valor, a célula fica em branco.
METRIC_BREAKDOWN
Seção intitulada “METRIC_BREAKDOWN”=PLAIDXL.METRIC_BREAKDOWN(name, breakdown, [filter], ...)
Retorna a métrica dividida por uma coluna: duas colunas, cada membro de breakdown ao lado do seu valor, do maior valor para o menor, sem linha de cabeçalho.
name— o nome da métrica, um de seus sinônimos ou o ID dela.breakdown— a coluna pela qual detalhar a métrica, uma pela qual a métrica possa ser detalhada.filter— um filtroDIMENSION_REPR. Passe quantos precisar.
=PLAIDXL.METRIC_BREAKDOWN("Net Revenue", "Region")Os membros sem valor vêm por último, com um valor em branco. Quando nenhuma linha corresponde, retorna uma linha: um membro vazio e 0.
Erros de métrica
Seção intitulada “Erros de métrica”Uma métrica que não pode ser calculada exibe #VALUE!; passe o mouse sobre a célula para ver o motivo:
| Mensagem | O que fazer |
|---|---|
| Métrica desconhecida ou coluna desconhecida | Verifique o nome. Quando há correspondências próximas, a mensagem as lista depois de Did you mean. |
| O nome corresponde a mais de uma métrica | Use o nome completo da métrica ou o ID dela. |
| 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 administrador que atualize o espaço de trabalho. |
| PlaidCloud is busy; try again in um número de segundos | O PlaidXL já tentou novamente. Recalcule depois do tempo informado. |
| Choose a project in the PlaidXL pane first. | Vincule a pasta de trabalho 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 o espaço de trabalho. As outras células do mesmo recálculo continuam respondendo. |
Blocos de construção
Seção intitulada “Blocos de construção”Essas funções não leem dados por conta própria. Cada uma retorna um pequeno trecho de texto que descreve uma parte de um cálculo, pronto para ser passado a CELL, CELLS ou DRILL. Coloque-as em células que você referencia, para que uma única alteração — um período diferente, por exemplo — atualize todas as fórmulas que as usam.
TABLE_REPR
Seção intitulada “TABLE_REPR”=PLAIDXL.REPR.TABLE_REPR(table_name)
A tabela da qual CELL e CELLS leem, pelo nome dela 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 se expande em uma célula por coluna; passe-o para 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 destes valores, em minúsculas:
| Valor | Retorna |
|---|---|
sum |
O total (o padrão quando você 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 para cada coluna pela qual você quiser filtrar.
dimension_name— o nome de uma coluna da tabela — a coluna que contém os valores da dimensão, como"Region". Ele deve corresponder exatamente ao nome da coluna; uma coluna que não está na tabela retorna um erro.start_node— o nó até o qual consolidar, como"EMEA". Em uma coluna que não está vinculada a uma dimensão, o valor a ser correspondido.hierarchy— a hierarquia alternativa pela qual consolidar o nó. O padrão é"main".
Referencie uma célula para o nó a fim de criar uma grade: =PLAIDXL.REPR.DIMENSION_REPR("Region", $A7). Espaços à esquerda e à direita são ignorados; assim, você pode apontar para os nomes de nós recuados que DRILL organiza.
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 detalhamento escrita por extenso:
d_key |
Detalha até |
|---|---|
"all" |
Todos os descendentes |
"leaves" |
Somente as folhas, que são os nós sem nada abaixo deles |
"1 level", "2 levels", … |
Essa quantidade de gerações para baixo |
">[...]" |
A chave de detalhamento escrita por extenso, como na tabela seguinte |
Escreva o número em algarismos: "2 levels", não "two levels". Um drill inicial é ignorado; portanto, "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 sempre é incluído. Números negativos contam para cima a partir das folhas de cada ramo, de modo que uma hierarquia irregular funciona como você esperaria.
| Chave | Inclui |
|---|---|
>[*] ou >[:] |
Todos os nós |
>[] ou >[-1] |
Somente as folhas |
>[n] |
O nó de partida e n gerações abaixo dele. >[0] é somente o nó de partida. |
>[a:] |
O nó de partida, depois a geração a e tudo abaixo dela |
>[a:b] |
O nó de partida, depois as gerações de a até b - 1 |
>[0:-k] |
O nó de partida e todo nó que tenha pelo menos k gerações abaixo dele, de modo que as últimas k gerações de cada ramo ficam de fora. >[0:-1] é todo nó, 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 na ordem da hierarquia, cada um sob o seu próprio pai, e os grupos da estrutura de tópicos do Excel seguem a mesma ordem. Espaços dentro de uma chave são ignorados. Uma chave que não corresponde a nenhuma dessas formas retorna um erro que lista as formas válidas.
Inserir uma fórmula pelo painel de tarefas
Seção intitulada “Inserir uma fórmula pelo painel de tarefas”A guia Formulas do painel de tarefas escreve uma fórmula para você. Abra-a pelo painel de tarefas, com Formula… na faixa de opções 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 digite a tabela e, opcionalmente, um número máximo de linhas. - One number (
CELL) — escolha ou digite a tabela, escolha a Column to total e How to combine the values. - A list of dimension nodes (
DRILL) — escolha ou digite a dimensão e o nó de partida, escolha até onde detalhar e, opcionalmente, uma Hierarquia alternativa, nós a excluir e nós a abrir. Linhas mostra uma prévia dos nós que o detalhamento lista. Consulte Detalhamento personalizado. - A business metric (
METRIC) — consulte Inserir uma métrica.
A prévia Formula mostra o resultado à medida que você preenche os campos. Clique em Insert in active cell (ou pressione Ctrl+Enter) para colocá-la na célula selecionada, ou em Copiar para colá-la você mesmo. Escolher uma tabela na guia Tabelas ou uma dimensão na guia Dimensões preenche o campo correspondente.
Inserir uma métrica
Seção intitulada “Inserir uma métrica”Clique em Metric… no grupo Inserir da faixa de opções ou escolha A business metric na guia Formulas.
- Em Metric, digite parte do nome ou de um sinônimo de uma métrica, como
revenue. Cada correspondência mostra o valor atual e a descrição. - Use as teclas de seta ou clique para escolher uma métrica.
- Opcionalmente, adicione filtros: escolha uma Dimensão, digite 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.
Relacionados
Seção intitulada “Relacionados”- Criar um relatório — uma hierarquia na lateral, valores na parte superior
- Trabalhar com tabelas e dimensões — escolha o projeto do qual as funções leem
- Usar dimensões — hierarquias principal e alternativas, e como os nós se consolidam
- Projetar uma hierarquia de dimensão — crie a hierarquia na qual o seu relatório se consolida