passos/configuração.md

@@ -4,7 +4,11 @@ Existe um arquivo `config.yaml.example` que pode ser copiado para se obter uma b
 
 Uma vez que o arquivo foi criado basta preenchê-lo.
 
-## *connection*
+## Arquivo
+
+Primeiramente uma desctrição de cada campo do arquivo de configuração.
+
+### *connection*
 
 O primeiro campo do arquivo de configuração é o *connection* que descreve a conexão do Blendb com o banco de dados. Os seguintes parâmetros devem ser preenchidos
 
@@ -16,7 +20,7 @@ O primeiro campo do arquivo de configuração é o *connection* que descreve a c
 * **max**: Máximo de conexões na Pool de conexões.
 * **idleTimeoutMillis**: Tempo que uma conexão com o banco de dados deve ficar inativa para ser encerrada.
 
-## *struct*
+### *struct*
 
 Essa seção é relacionada a estrutura do banco de dados. A principio essas opções são utilizadas apenas para testes.
 
@@ -25,11 +29,11 @@ Essa seção é relacionada a estrutura do banco de dados. A principio essas op
 
 Utiliando esse guia, você deve colocar o valor de ambos os campos como `false`.
 
-## *schema*
+### *schema*
 
 Essa é a seção mais importante e mais trabalhosa do processo. O objetivo dela é ensinar ao Blendb quais são as agregações disponíveis, quais são as métricas e quais são as dimensões.
 
-###  *metrics*
+####  *metrics*
 
 Nessa seção é informada as métricas do Blendb. Essa seção é uma lista de objetos, onde cada objeto descreve uma métrica. Para um exemplo visualize o arquivo *ci_test.yalm.example*.
 
@@ -47,7 +51,7 @@ Nessa seção é informada as métricas do Blendb. Essa seção é uma lista de
 Todas essas informações são fornescidas pela API. Ajuda na realização de consultas saber o que esse dado é.
 
 
-###  *dimensions*
+####  *dimensions*
 
 Nessa seção é informada as dimensões do Blendb. Essa seção é uma lista de objetos, onde cada objeto descreve uma dimensão. Para um exemplo visualize o arquivo *ci_test.yalm.example*.
 
@@ -70,7 +74,7 @@ Atualmente só existem relações para datas. Recomendamos colocar como o tipo d
 
 Todas essas informações são fornescidas pela API. Ajuda na realização de consultas saber o que esse dado é.
 
-###  *views*
+####  *views*
 
 Nessa seção é informada as agregações do Blendb. Essa seção é uma lista de objetos, onde cada objeto descreve uma agregação. Para um exemplo visualize o arquivo *ci_test.yalm.example*.
 
@@ -84,3 +88,32 @@ Nessa seção é informada as agregações do Blendb. Essa seção é uma lista
 * **metrics**: Lista de métricas: Esse atribuito é uma lista que contém o nome de uma métrica que essa agregação contém. Esse nome deve  ser identico ao especificado no atribuito *name* da métrica.
 * **keys**: Lista de dimensões que definem a chave priméria da agregação. A chave primária da agregação é sempre um sub-conjunto das dimensões. Caso esse atributo não seja especificado assume-se que todas as dimensões formam a chave. Esse atribuito é uma lista que contém o nome de uma dimensão que essa agregação contém. Esse nome deve  ser identico ao especificado no atribuito *name* da dimensão.
 
+## Preenchendo
+
+As seções *connection* e *struct* são simples de se preencher. Basta utilizar os parâmetros do banco de dados para a *connection* e colocar todos os atributos como `false` na struct.
+
+A seção esquema busca descrever o banco de dados e exige mais detalhes no preenchimento.
+
+Como regra geral, todas as fontes de dados (tabelas) no banco de dados se transformam em agregações. Recomendamos que o atributo **alias** da agregação seja colocado como o nome da tabela. Essas agregaçẽos também devem ter o atributo **origin** como `true`. O campo **file** deve receber o seguinte caminho `../database/views/{{name}}.sql` onde {{name}} é um identificador da tabela. Pode ser o mesmo que o *alias* ou uma sigla.
+
+Agora os atributos de cada tabela devem ser transformados em métricas e dimensões. Observe que a relação entre dimensões e métricas não é necessariamente "de um para um".
+Alguns atributos podem ser ignorados (pouco commum) e um atributo pode se desdobrar em várias métricas (bastante comum) e várias dimensões (menos comum).
+
+A princípio os atributos que descrevem características são colocados como dimensões. Em caso de dúvida coloque todos como dimensões e vá movendo para métricas aos poucos.
+
+Métricas podem ser apenas valores numéricos, então qualquer valor que não seja numérico é necessariamente uma dimensão.
+
+Um valor que se quer obter a partir de uma combinação de registros é uma métrica. A forma de combinação define a função de agregações.
+
+Se quer-se combinar um valor de diferentes formas, cada uma delas caracterizara uma nova métrica. Por exemplo, considere um dado de uso de rede. Pode-se querer obter a banda média e um pico de rede. São duas formas diferentes de se combinar os dados, usando a função média e máximo respectivamente. Logo ao invés de uma métrica "uso de rede", não necessárias duas "uso de rede médio" "pico de rede (uso de rede máximo)".
+
+Em caso de dúvida, pode-se criar uma métrica para cada função de agregação (com exeção de `count`) para cada atributo considerado um métrica.
+
+Como regra geral, as tabelas possuem no máximo uma métrica `count` que conta a quantidade de linhas da tabela. Algumas podem não possuir, mas em caso de dúvida adicione. O nome , em geral é "Quantidade de alguma coisa". Por exemplo em um tabela onde cada registro é um contado e é registrado o uso de rede, pdoeria ser "Quantidade de contatos". Em uma tabela que descreve experimentos científicos, a métrica poderia ser "Quantidade de experimentos".
+
+Atributos que representam o mesmo valor em diferentes tabelas (Atributos que normalmente são chaves estrangeiras) devem opssuir **exatamente** o mesmo nome em todas as agregações.
+
+Nomes de atributos como *id* ou *nome*, onde o valor é implicito pela tabela que ele se encontra são desencorajados. Como alternativa busca um nome significativo, ou adicione a localização no atributo como "id cliente", "nome do usuário". Lembre que no Blendb os atributos são da base como um todo. Atributos devem ter o mesmo nome **apenas** se forem o mesmo.
+
+Por fim basta definir quais dimensões definem a chave. A pergunta que deve ser feita para definir uma chave é "Qual conjunto de dimensões define unicamente um registro ?".
+Em geral a chave é pequena. Lembre-se que a chave afeta a capacidade do Blendb executar junções de agregações e não deve ser desnecessariamente grande ou os resultados obtidos podem ser comprometidos.
\ No newline at end of file