Pesquisa com o ReportM

Como referido anteriormente, o ReportM suporta 3 tipos de pesquisa para obter dados, que são depois utilizados para preencher folhas do excel.

• Pesquisa por Definição. É uma pesquisa de texto livre sobre uma definição.
• Pesquisa por Domínio. É uma pesquisa de texto livre sobre as definições de um domínio, aplicando a pesquisa às várias definições do domínio. As instâncias encontradas em cada definição são concatenadas numa única listagem.
• Pesquisa Elasticsearch. É uma pesquisa Elasticsearch estruturada (que pode conter agregações) sobre o índice de uma definição.

Pesquisa por Definição

A Pesquisa por Definição executa uma query sobre uma definição, utilizando as instâncias devolvidas como dados do relatório. Esta query é escrita utilizando pesquisa livre. Cada instância irá tornar-se uma linha no relatório, onde os campos selecionados serão as colunas.

Numa pesquisa por definição, os seguintes parâmetros em COB_SHEETS significam:

Parâmetro	Significado
Target	Nome da definição a pesquisar
search	A consulta de pesquisa livre que pretende utilizar

Exemplo

Para criar um relatório com a lista de todos os países que utilizam o Euro como moeda, poderíamos utilizar um cob_config_v2 como:

E uma folha Countries com o seguinte aspecto:

E o resultado final seria:

Pesquisa por Domínio

A Pesquisa por Domínio funciona da mesma forma que a Pesquisa por Definição, mas o Target é o nome de um domínio.

Numa pesquisa por domínio, os seguintes parâmetros em COB_SHEETS significam:

Parâmetro	Significado
Target	Nome do domínio ao qual as definições a serem pesquisadas pertencem
search	A query a executar a todas as definições do domínio

Por exemplo, o domínio @ELRD E-learning Demo tem as seguintes definições:

• Countries
• Countries Series
• Country Events
• Country Trip Ideas

Se o nosso cob_config_v2 tiver o seguinte aspecto:

E Countries tiver as seguintes colunas:

TIP

A coluna definitionName fica disponível para cada instância, indicando a definição à qual pertence.

Produziria:

Note que as definições que não possuem o campo deixam essa coluna vazia.

WARNING

Se uma definição não tiver um campo especificado no cabeçalho de uma Target Sheet, essa coluna ficará vazia para todas as instâncias dessa definição.

Pesquisa Elasticsearch

A Pesquisa Elasticsearch executa uma query Elasticsearch sobre o índice de uma definição.

Numa pesquisa Elasticsearch, os seguintes parâmetros em COB_SHEETS significam:

Parâmetro	Significado
Target	Índice da definição. Os índices têm o seguinte nome: recordm-<id da definição>
search	A query Elasticsearch que pretende utilizar. Pode incluir agregações.

Dados do Relatório em Relatórios Elasticsearch

Os campos que especificamos no relatório — na Target Sheet — afectam o tipo de dados devolvidos pela pesquisa Elasticsearch. Considere, por exemplo, a seguinte query, executada sobre a definição Countries, que inclui uma agregação:

{
  "query": {
    "match_all": {}
  },
  "aggs" : { 
    "per_currency" : { // Nome do bucket, escolhido por nós
      "terms": {
        "field": "currency_unit.raw",
        "size": 100
      },
      "aggs": {
        "count": { // Nome do sub-bucket, escolhido por nós
          "cardinality": {
            "field": "id.raw"
          }
        }
      }
    }
  }
}

Esta consulta conta o número de países que têm cada tipo de moeda.

• Se utilizarmos per_currency ou count como nomes de campos no nosso relatório, o ReportM utilizará os dados de agregação para preencher essas colunas.
• Se utilizarmos alguns dos nomes de campos da definição, como long_name, o ReportM utilizará as instâncias.

Isto significa que, ao consultar o Elasticsearch directamente, podemos efectuar uma pesquisa sobre instâncias e tirar partido de todo o poder de consulta do Elasticsearch. No entanto, devemos ter cuidado para não misturar diferentes tipos de dados (agregados vs. não agregados), pois isso irá provavelmente gerar relatórios indesejados.

NOTE

Nas consultas Elasticsearch, os campos têm de ser referenciados no seu formato de pesquisa (sem espaços, tudo em minúsculas).

Nas agregações, devemos utilizar sempre o .raw de um campo, pois é nesse campo que armazenamos o valor de um campo como keyword, o que permite ao Elasticsearch utilizá-lo em agregações.

Buckets nos relatórios

Se utilizarmos nomes de buckets no nosso relatório, cada bucket irá gerar uma linha para os seus sub-buckets (ou apenas uma linha se não tiver sub-buckets). Considere, por exemplo, a seguinte consulta:

{
  "query": {
    "match_all": {}
  },
  "aggs" : {
    "per_currency" : {
      "terms": {
        "field": "currency_unit.raw",
        "size": 100
      },
      "aggs": {
        "per_income": {
          "terms": {
            "field": "income_group.raw"
          },
          "aggs": {
            "count": {
              "cardinality": {
                "field": "id.raw"
              }
            }
          }
        }
      }
    }
  }
}

Neste caso, dividimos os países pelos seus tipos de rendimento para cada unidade monetária. Isto significa que teremos uma linha para cada combinação de per_currency e per_income presente nos nossos dados.

Exemplo

Vamos exemplificar como utilizar pesquisas Elasticsearch com a query acima, na qual contamos quantos países de cada grupo de rendimento existem para cada moeda.

Assim, o nosso cob_config_v2 teria o seguinte aspecto:

TIP

É altamente recomendado escrever a sua query Elasticsearch noutro programa e colá-la no Excel.

Para ajudar a escrever estas consultas, o Kibana é frequentemente um bom ponto de partida. Permite-nos fazer "Inspect" da query por detrás de um gráfico e utilizá-la aqui.

Enquanto a nossa folha Countries tem o seguinte aspecto:

Produziria: