Housekeeping

pages/analytics.md

@@ -34,7 +34,7 @@ curl -XGET http://localhost:9200/mycompany/funcionarios/_search?pretty -d '
 }'
 ```
 
-O parâmetro **"aggs"** é utilizado para descrevermos todas as nossas agregações que serão realizadas. O **"maiores_interesses"** foi um nome fictício (como um _apelido_), dado para o nosso conjunto de resultados e poderia ter sido qualquer outro (ex: total_de_interesses, interesses_gerais, etc). Após nomear o nosso conjunto de resultados, usamos o parâmetro **"terms"**, para descrevermos por qual(is) **"field(s)"** queremos agregar os resultados.
+O parâmetro **"aggs"** é utilizado para descrevermos todas as nossas agregações que serão realizadas. O parâmetro **"maiores_interesses"** foi um nome fictício (como um _apelido_), dado para o nosso conjunto de resultados e poderia ter sido qualquer outro (ex: total_de_interesses, interesses_gerais, etc). Após nomear o nosso conjunto de resultados, usamos o parâmetro **"terms"** para descrevermos por qual(is) **"field(s)"** queremos agregar os resultados.
 
 Para facilitar a visualização, vamos observar apenas o final do resultado obtido:
 
@@ -71,7 +71,7 @@ Para facilitar a visualização, vamos observar apenas o final do resultado obti
 
 ```
 
-Dentro de **"maiores_interesses"**, temos a separação dos resultados por **"buckets"**, que nos revelam a quantidade de documentos que foram encontrados fazendo menção a cada resultado. Algo que mais "embelezado" ficaria assim:
+Dentro de **"maiores_interesses"** temos a separação dos resultados por **"buckets"**, que nos revelam a quantidade de documentos que foram encontrados fazendo menção a cada resultado. Algo que mais "embelezado" ficaria assim:
 
 | Interesses        | Documentos Encontrados
 | ------------- |:-------------:|
@@ -81,7 +81,7 @@ Dentro de **"maiores_interesses"**, temos a separação dos resultados por **"bu
 | Games | 1|
 | Musculação | 1|
 
-Ou seja, com uma simples pesquisa conseguimos encontrar fatores em comum sobre nossos funcionários e agora sabemos quais sãos os maiores interesses dentro de nossa empresa. Possuímos poucos dados para brincar até o momento, mas imagine em uma empresa com 5.000 funcionários. Será que conseguimos tirar algum proveito disso ? Será que conseguimos correlacionar nossos dados para encontrar benefícios que possam ser mais úteis para nossos colaboradores ? Pense só, temos poucos dados, mas já sabemos que a maioria dos funcionários gostam de "música" e "esportes".
+Ou seja, com uma simples pesquisa conseguimos encontrar fatores em comum sobre nossos funcionários e agora sabemos quais sãos os maiores interesses dentro de nossa empresa. Possuímos poucos dados para brincar até o momento, mas imagine em uma empresa com 5.000 funcionários. Será que conseguimos tirar algum proveito disso ? Será que conseguimos correlacionar nossos dados para encontrar benefícios que possam ser mais úteis para nossos colaboradores ? Pense só, temos poucos dados, mas já sabemos que a maioria dos nossos funcionários gostam de "música" e "esportes".
 
 Apesar de abordarmos tarefas simples com os tipos de pesquisa do Elasticsearch, a quantidade de operações, agregações e filtros possíveis são quase infinitos ! Tudo vai depender da quantidade de dados que você possui e a quantidade de regras que você quer especificar em suas buscas.
 

pages/cluster_shards_replicas.md

@@ -1,5 +1,5 @@
 ## Cluster, Shards e Replicas
 
-Lembra que eu havia dito que o Elasticsearch foi feito para o _Cloud Computing_ ? Nesta seção explicaremos como a redundância e a alta disponibilidade são tratadas internamente pela ferramenta, através de alguns conceitos de _clusterização_ e replicação de dados. Já adianto que as seções posteriores irão apresentar uma certa dificuldade, portanto preste __bastante__ atenção em cada ponto aqui explicado, pois eles são essenciais para compreender a ferramenta mais a fundo.
+Lembra que eu havia dito que o Elasticsearch foi feito para o _Cloud Computing_ ? Nas próximas seções, explicaremos como a redundância e a alta disponibilidade são tratadas internamente pela ferramenta através de alguns conceitos de _clusterização_ e replicação de dados. Preste __bastante__ atenção em cada ponto que será explicado, pois eles serão essenciais para compreender a ferramenta mais a fundo.
 
 Próximo: [Node e Cluster](/pages/node_cluster.md)

pages/containers.md

@@ -33,6 +33,8 @@ output {
 }
 ```
 
+__OBS:__ É possível utilizar apenas __uma__ instância de Logstash com __um__ arquivo de configuração subdividido pelos tipos de entrada de dados, o que faz mais sentido do que subir diversas instâncias para cada .conf que criamos. Estamos fazendo desta forma, apenas para facilitar o entendimento.
+
 A configuração acima, fará com que o nosso Logstash receba as logs do nosso container através do driver __[gelf](https://docs.docker.com/config/containers/logging/gelf/)__. Estamos associando a porta __12201__, onde o Logstash receberá as entradas e enviará para o Elasticsearch, inserindo os dados no index "docker".
 
 Faça a subida do Logstash utilizando este novo arquivo de configuração:

pages/contexts.md

@@ -12,7 +12,7 @@ Neste tipo de inserção, informamos o index, o type e o id (1 no exemplo acima)
 curl -XGET http://localhost:9200/mycompany/funcionarios/1
 ```
 
-A nível de teste, não há problemas neste tipo de abordagem. Mas não é comum informarmos o id no momento da inserção do dado, por 'N' motivos. Para ids, geralmente deixamos o Elasticsearch fazer a criação dinamicamente. Ou seja, você pode inserir dados no contexto que desejar sem precisar se preocupar com um número de id. Vamos criar mais um type para o nosso index "mycompany" chamado "diretores":
+A nível de teste não há problemas neste tipo de abordagem, mas não é comum informarmos o id no momento da inserção do dado por 'N' motivos. Para ids, geralmente deixamos o Elasticsearch fazer a criação dinamicamente. Ou seja, você pode inserir dados no contexto que desejar sem precisar se preocupar com um número de id. Vamos criar mais um type para o nosso index "mycompany" chamado "diretores":
 
 ```
 curl -XPOST http://localhost:9200/mycompany/diretores/ -d '
@@ -25,7 +25,9 @@ curl -XPOST http://localhost:9200/mycompany/diretores/ -d '
 }'
 ```
 
-Veja que utilizamos o verbo HTTP __POST__ ao invés de __PUT__. Como vimos muito anteriormente, o verbo __PUT__ fala para o Elasticsearch armazenar o dado em uma URL específica, ou seja, em um caminho completo. Já o __POST__ diz para o Elasticsearch armazenar o dado _ABAIXO_ de uma URL. Algo parecido com isso:
+Veja que utilizamos o verbo HTTP __POST__ ao invés de __PUT__. Como vimos muito anteriormente, o verbo __PUT__ fala para o Elasticsearch armazenar o dado em uma URL específica, ou seja, em um caminho completo. Já o __POST__ diz para o Elasticsearch armazenar o dado _ABAIXO_ de uma URL. Leia o diálogo abaixo para entender melhor:
+
+#### PUT VS ELASTICSEARCH
 
 ```
 PUT:"Oi Elasticsearch."
@@ -36,15 +38,17 @@ PUT:"Leva esse documento nesse endereço aqui ó... Bairro: mycompany, Rua: dire
 Elasticsearch:"Beleza."
 ```
 
+#### POST VS ELASTICSEARCH
+
 ```
 POST:"E ai Elasticsearch, tudo bom :) ?"
 Elasticsearch:"Lá vem você denovo pra me dar trabalho..."
 POST:"Que nada ! Bom.. na verdade, eu gostaria que você enviasse um documento em um endereço pra mim."
 Elasticsearch:"Ta... ta... me passa o endereço."
-POST:"Então... é no Bairro: mycompany, na Rua: diretores e... hmmmm."
+POST:"Então... fica no Bairro: mycompany, na Rua: diretores e... hmmmm."
 Elasticsearch:"Hmmm o que ? Qual é o número ?"
 POST:"Esse é o problema.. eu não tenho o número, mas precisamos entregar isso agora :("
-Elasticsearch:"Ah.. que ótimo. Vou entregar em qualquer número que eu escolher então !"
+Elasticsearch:"Ah.. que ótimo. Nesse caso, vou entregar em qualquer número que eu escolher !"
 ```
 
 Tirando o _incrível mau humor_ do Elasticsearch em realizar inserções de dados, é mais ou menos isso que acontece. Se não informarmos o id, o Elasticsearch gera automaticamente um id para o nosso documento. Vamos ver qual o id que ele escolheu para o nosso _fino_ diretor:

pages/counting.md

@@ -1,6 +1,6 @@
 ## Contagem de Documentos
 
-Eu odiava ver tutoriais que me ensinavam a baixar a aplicação, para logo em seguida pedir para subir e fazer alguma outra coisa. Chegou a hora de dar o troco ! Vamos subir novamente a nossa instância de Elasticsearch e vamos contar quantos documentos existem em nossos índices:
+Eu odiava ver tutoriais que me ensinavam a baixar a aplicação, para logo em seguida pedir para subir e fazer alguma outra coisa. Chegou a hora de dar o troco ! Vamos subir novamente a nossa instância de Elasticsearch para realizar a contagem de documentos existentes em nossos índices:
 
 ```
 nohup ./elasticsearch &

pages/elasticsearch.md

@@ -2,7 +2,7 @@
 
 O `elasticsearch` é uma ferramenta de buscas _open source_ desenvolvido em Java, assim como é uma solução NoSQL de armazenamento de dados, ou seja, ele não segue os padrões de bancos de dados SQL comuns (como o MySQL, por exemplo).
 
-Seu desenvolvimento tem como base o [Apache Lucene](https://github.com/apache/lucene-solr), que é uma biblioteca Java de pesquisa _full text_ e que é também, o motor de busca open source mais avançado oferecido hoje em dia. Porém, usar todo o poder de fogo do Lucene exige um certo esforço, afinal, por ser apenas uma biblioteca, você precisa trabalhar com o Java para integrá-lo com sua aplicação (e esta tarefa pode apresentar uma certa complexidade).
+Seu desenvolvimento tem como base o [Apache Lucene](https://github.com/apache/lucene-solr), que é uma biblioteca Java de pesquisa _full text_ e que é também, o motor de busca open source mais avançado oferecido hoje em dia. Porém, usar todo o poder de fogo do Lucene exige um certo esforço, afinal por ser apenas uma biblioteca, você precisa trabalhar com o Java para integrá-lo com a sua aplicação (e esta tarefa pode apresentar uma certa complexidade).
 
 O Elasticsearch no entanto, se aproveita do Lucene na _indexação_ e pesquisa de documentos, retirando a sua complexidade através de uma API RESTful super fácil de se utilizar. Além disso, vamos citar algumas características que o tornam uma ferramenta excelente e extremamente veloz:
 

pages/full-text.md

@@ -1,6 +1,6 @@
 ## Full-Text
 
-Na pesquisa full-text você simplesmente pesquisa o que você quer, sem passar nenhuma regra, agregação ou algo do tipo. Quando apresentarmos o Kibana, este tipo de pesquisa vai se apresentar de forma mais simples ainda, como uma pesquisa no Google. Vamos pesquisar as palavras "easy to use" no campo "tweet" do nosso index:
+Na pesquisa full-text você simplesmente pesquisa o que você quer sem passar nenhuma regra, agregação ou algo do tipo. Quando apresentarmos o Kibana, este tipo de pesquisa vai se apresentar de forma mais simples ainda, como uma pesquisa no Google. Vamos pesquisar as palavras "easy to use" no campo "tweet" do nosso index:
 
 ```
 curl -XGET http://localhost:9200/twitter/tweet/_search?pretty -d '
@@ -13,7 +13,7 @@ curl -XGET http://localhost:9200/twitter/tweet/_search?pretty -d '
 }'
 ```
 
-Se você não fez nenhuma alteração no script [tweets.sh](/scripts/tweets.sh), você deve estar visualizando 3 tweets agora, como estes aqui:
+Se você não fez nenhuma alteração no script [tweets.sh](/scripts/tweets.sh), você deve estar visualizando 3 tweets como resposta, como estes abaixo:
 
 ```
 {
@@ -72,11 +72,11 @@ Se você não fez nenhuma alteração no script [tweets.sh](/scripts/tweets.sh),
 
 Talvez você não tenha reparado, mas você acabou de fazer uma pesquisa full text. Mas calma ai... porque eu tenho três respostas para a pequisa "easy to use" se em apenas um dos tweets eu realmente tenho as palavras "easy to use" ?
 
-Bem, é ai que a graça (ou desgraça) do full text entra em ação. Repare que os três tweets retornados possuem a palavra "easy". Como a sua busca não possui nenhum filtro ou parametrização adicional, qualquer uma das três palavras que compõe a sua busca (easy to use), serão pesquisadas no index informado. Porém no primeiro resultado (tweet do Tom Michael), vemos que o campo **"_score"** possui o número **"1.9187583"** como valor, correto ? Compare este número com o "\_score" dos outros resultados...
+Bem, é ai que a graça (ou desgraça) do full text entra em ação. Repare que os três tweets retornados possuem a palavra "easy". Como a sua busca não possui nenhum filtro ou parametrização adicional, qualquer uma das três palavras "easy", "to" e "use" que compõe a sua busca, serão pesquisadas no index informado. Porém, no primeiro resultado (tweet do Tom Michael), vemos que o campo **"_score"** possui o número **"1.9187583"** como valor, correto ? Compare este número com o "\_score" dos outros resultados...
 
 O Elasticsearch verifica a relevância de um documento pela proximidade da busca realizada. Como o primeiro resultado é o que mais se aproxima da busca feita, por possuir as três palavras pesquisadas, este documento recebe um número de \_score mais alto do que os demais. É assim que o Elasticsearch mede a relevância de uma pesquisa feita com o resultado encontrado.
 
-Este é o tipo de pesquisa mais simples de se fazer, porém é também o mais suscetível a falhas por acabar retornando resultados que podem não ser relevantes (e por conta do campo **"_all"** que será explicado em breve). Agora, se quisermos pesquisar a sequência exata "easy to use", podemos utilizar o recurso "match_phrase" em nossa busca:
+Este é o tipo de pesquisa mais simples de se fazer e também, o mais suscetível a falhas, por acabar retornando resultados que podem não ser relevantes para a sua busca e por conta do campo **"_all"** que será explicado em breve. Agora, se quisermos pesquisar a sequência exata das palavras "easy to use", podemos utilizar o recurso "match_phrase" em nossa busca:
 
 ```
 curl -XGET http://localhost:9200/twitter/tweet/_search?pretty -d '
@@ -113,7 +113,7 @@ O campo "\_all" deste documento ficaria assim:
 }
 ```
 
-Sendo assim, ao realizarmos uma busca full-text sem passarmos nenhum campo como parâmetro, o Elasticsearch realiza a pesquisa em todos os campos "\_all" do index escolhido, o que é muito mais rápido do que ter que avaliar campo a campo de cada documento. Porém, pode acontecer de um campo diferente do que você quer buscar possuir um valor igual ao que você procura. Ficou estranho né ? Veja o exemplo abaixo:
+Sendo assim, ao realizarmos uma pesquisa full-text sem passarmos nenhum campo como parâmetro, o Elasticsearch realiza a pesquisa em todos os campos "\_all" do index escolhido, o que é muito mais rápido do que ter que avaliar campo a campo de cada documento. Porém, pode acontecer de um campo diferente do que você quer buscar possuir um valor igual ao que você procura. Ficou estranho né ? Veja o exemplo abaixo:
 
 ```
 {
@@ -146,7 +146,7 @@ Ao inserir estes dois documentos, o Elasticsearch geraria para cada um, as segui
 
 Se eu quiser saber quantas pessoas de nome "Carlos" eu tenho no meu index e fizer uma pesquisa full-text para encontrar "Carlos", quantos retornos eu terei ? E se eu pesquisar por "Freitas", quantos retornos eu terei ?
 
-Se o meu index só possuir estes dois documentos apenas, o retorno da nossa pesquisa seria: **dois** Carlos e **um** Freitas, mesmo eu só possuindo **um** Carlos e **nenhum** Freitas.
+Se o meu index só possuir apenas estes dois documentos, o retorno da nossa pesquisa seria: **dois** Carlos e **um** Freitas, mesmo eu só possuindo **um** Carlos e **nenhum** Freitas.
 
 Estamos entendidos com o full-text ?
 

pages/index_type_document.md

@@ -5,11 +5,11 @@ Agora que fizemos a instalação e garantimos que o nosso Elasticsearch está op
 ```
 curl -XPUT http://localhost:9200/mycompany/funcionarios/1 -d '
 {
-"nome": "João Silva",
-"idade": 19,
-"endereco": "Avenida da Magia",
-"hobbies": ["Tocar guitarra", "Acampar com a familia"],
-"interesses": "musica"
+  "nome": "João Silva",
+  "idade": 19,
+  "endereco": "Avenida da Magia",
+  "hobbies": ["Tocar guitarra", "Acampar com a familia"],
+  "interesses": "musica"
 }'
 ```
 
@@ -19,24 +19,24 @@ Provavelmente você recebeu uma resposta parecida com esta:
 {"_index":"mycompany","_type":"funcionarios","_id":"1","_version":1,"result":"created","_shards":{"total":2,"__successful__":1,"failed":0},"created":true}
 ```
 
-Isto significa que o nosso documento JSON foi _indexado_ com sucesso. O verbo PUT utilizado, basicamente diz para o Elasticsearch, "guarde este documento __NESTA__ url" (o POST se assemelha em funcionalidade, porém dizendo a frase: "guarde o documento __ABAIXO__ desta url". Entenderemos melhor a diferença posteriormente).
+Isto significa que o nosso documento JSON foi _indexado_ com sucesso. O _verbo_ PUT utilizado, basicamente diz para o Elasticsearch: "guarde este documento __NESTA__ url" (o POST se assemelha em funcionalidade, porém dizendo a frase: "guarde o documento __ABAIXO__ desta url". Entenderemos melhor a diferença posteriormente).
 
 Para facilitar o entedimento do conceito de _index_, _type_ e _document_, vamos fazer uma analogia com um banco de dados SQL padrão:
 
-| MySQL        | Banco de Dados           | Tabela  | Chave Primária | Linha | Coluna
+| MySQL        | Banco de Dados | Tabela  | Chave Primária | Linha | Coluna
 | ------------- |:-------------:| -----:|-----:|-----:|-----:|
 | __Elasticsearch__        | __Index__           | __Type__  | __Id__ | __Document__ | __Field__
 | ------------- | mycompany| funcionarios|1|Documento JSON|nome, idade...|
 
 
-__Importante:__ Os termos "indexar" e "index" possuem significados diferentes no universo do Elasticsearch, e também se diferenciam do conceito de _índices_ utilizados em [Banco de Dados](https://pt.wikipedia.org/wiki/%C3%8Dndice_(estruturas_de_dados)). Indexar no Elasticsearch é o mesmo que adicionar um documento JSON (como realizar um INSERT), e index é uma forma de separar logicamente dados de diferentes propósitos.
+__OBS:__ Os termos "indexar" e "index" possuem significados diferentes no universo do Elasticsearch, e também se diferenciam do conceito de _índices_ utilizados em [Banco de Dados](https://pt.wikipedia.org/wiki/%C3%8Dndice_(estruturas_de_dados)). Indexar no Elasticsearch é o mesmo que adicionar um documento JSON (como realizar um INSERT), e index é uma forma de separar logicamente dados de diferentes propósitos.
 
 Ok, temos o nosso primeiro funcionário João Silva __indexado__ no nosso __index__ mycompany ! Vamos fazer a nossa primeira consulta:
 
 ```
 curl -XGET http://localhost:9200/mycompany/funcionarios/_search?pretty
 ```
 
-Neste comando, chamamos a API __search__, que é a API padrão de buscas do Elasticsearch (o parâmetro __?pretty__ é opcional e só serve para formatar a saída em JSON). Como não passamos nenhum parâmetro, a API sempre nos retorna os 10 primeiros resultados, que neste caso nos trouxe apenas o João (_we're hiring_). Sinta-se livre para criar e consultar mais funcionários para exercitar a sintáxe :) .
+Com o comando acima, chamamos a API padrão de buscas do Elasticsearch **_search** (o parâmetro __?pretty__ é opcional e só serve para formatar a resposta em JSON). Como não passamos nenhum parâmetro, a API sempre nos retorna os 10 primeiros resultados encontrados, que neste caso nos trouxe apenas o João (_we're hiring_). Sinta-se livre para criar e consultar mais funcionários para exercitar a sintáxe :) .
 
 Próximo: [Tipos e Formas de Pesquisa](/pages/types_forms.md)