# Siren Federate User Guide

print

- Prev
- Next

## Getting started

In this short guide, you will learn how you can quickly install the Siren Federate plugin in Elasticsearch, load two collections of documents inter-connected by a common attribute, and execute a relational query across the two collections within the Elasticsearch environment.

### Prerequisites

Unless you are using the complete Siren Platform package, you must download and installed the version of Elasticsearch that you want to use. If you do not have an Elasticsearch distribution, you can run the following commands where <version> is the version you want to use, for example 5.6.9:

    $ wget https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-<version>.zip
    $ unzip elasticsearch-<version>.zip
    $ cd elasticsearch-<version>

### Installing the Siren Federate Plugin

Before starting Elasticsearch, you have to install the Siren Federate plugin. Assuming that you are in your Elasticsearch installation directory, you can run the following command where <version> is the Siren Federate version:

    $ ./bin/elasticsearch-plugin install file:///<path to Siren Federate plugin>/siren-federate-<version>-SNAPSHOT-plugin.zip
    -> Downloading file:///<path to Siren Federate plugin>/siren-federate-<version>-SNAPSHOT-plugin.zip
    [=================================================] 100%
    @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
    @     WARNING: plugin requires additional permissions     @
    @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
    * java.io.FilePermission cloudera.properties read
    * java.io.FilePermission simba.properties read
    * java.lang.RuntimePermission accessClassInPackage.sun.misc
    * java.lang.RuntimePermission accessClassInPackage.sun.misc.*
    * java.lang.RuntimePermission accessClassInPackage.sun.security.provider
    * java.lang.RuntimePermission accessDeclaredMembers
    * java.lang.RuntimePermission createClassLoader
    * java.lang.RuntimePermission getClassLoader
    ...
    See http://docs.oracle.com/javase/8/docs/technotes/guides/security/permissions.html
    for descriptions of what these permissions allow and the associated risks.

    Continue with installation? [y/N]y
    -> Installed siren-federate

In case you want to remove the plugin, you can run the following command:

    $ bin/elasticsearch-plugin remove siren-federate

    -> Removing siren-federate...
    Removed siren-federate

### Starting Elasticsearch

To launch Elasticsearch, run the following command:

    $ ./bin/elasticsearch

In the output, you should see a line like the following which indicates that the Siren Federate plugin is installed and running:

    [2017-04-11T10:42:02,209][INFO ][o.e.p.PluginsService     ] [etZuTTn] loaded plugin [siren-federate]

### Loading Some Relational Data

We will use a simple synthetic data set for the purpose of this demo. The data set consists of two collections of documents: Articles and Companies. An article is connected to a company with the attribute `mentions`. Articles will be loaded into the `articles` index and companies in the `companies` index. To load the data set, run the following command:

    $ curl -H 'Content-Type: application/json' -XPUT 'http://localhost:9200/articles'
    $ curl -H 'Content-Type: application/json' -XPUT 'http://localhost:9200/articles/_mapping/article' -d '
    {
      "properties": {
        "mentions": {
          "type": "keyword"
        }
      }
    }
    '
    $ curl -H 'Content-Type: application/json' -XPUT 'http://localhost:9200/companies'
    $ curl -H 'Content-Type: application/json' -XPUT 'http://localhost:9200/companies/_mapping/company' -d '
    {
      "properties": {
        "id": {
          "type": "keyword"
        }
      }
    }
    '

    $ curl -H 'Content-Type: application/json' -XPUT 'http://localhost:9200/_bulk?pretty' -d '
    { "index" : { "_index" : "articles", "_type" : "article", "_id" : "1" } }
    { "title" : "The NoSQL database glut", "mentions" : ["1", "2"] }
    { "index" : { "_index" : "articles", "_type" : "article", "_id" : "2" } }
    { "title" : "Graph Databases Seen Connecting the Dots", "mentions" : [] }
    { "index" : { "_index" : "articles", "_type" : "article", "_id" : "3" } }
    { "title" : "How to determine which NoSQL DBMS best fits your needs", "mentions" : ["2", "4"] }
    { "index" : { "_index" : "articles", "_type" : "article", "_id" : "4" } }
    { "title" : "MapR ships Apache Drill", "mentions" : ["4"] }

    { "index" : { "_index" : "companies", "_type" : "company", "_id" : "1" } }
    { "id": "1", "name" : "Elastic" }
    { "index" : { "_index" : "companies", "_type" : "company", "_id" : "2" } }
    { "id": "2", "name" : "Orient Technologies" }
    { "index" : { "_index" : "companies", "_type" : "company", "_id" : "3" } }
    { "id": "3", "name" : "Cloudera" }
    { "index" : { "_index" : "companies", "_type" : "company", "_id" : "4" } }
    { "id": "4", "name" : "MapR" }
    '

    {
      "took" : 8,
      "errors" : false,
      "items" : [ {
        "index" : {
          "_index" : "articles",
          "_type" : "article",
          "_id" : "1",
          "_version" : 3,
          "status" : 200
        }
      },
      ...
    }

### Relational Querying of the Data

We will now show you how to execute a relational query across the two indices. For example, we would like to retrieve all the articles that mention companies whose name matches `orient`. This relational query can be decomposed in two search queries: the first one to find all the companies whose name matches `orient`, and a second query to filter out all articles that do not mention a company from the first result set. The Siren Federate plugin introduces a new Elasticsearch’s filter, named `join`, that enables you to define such a query plan and a new search API `_search` that enables you to execute this query plan. Below is the command to run the relational query:

    $ cur -H 'Content-Type: application/json' 'http://localhost:9200/siren/articles/_search?pretty' -d '{
       "query" : {
          "join" : {                     (1)
            "indices" : ["companies"],   (2)
            "on" : ["mentions", "id"],   (3)
            "request" : {                (4)
              "query" : {
                "term" : {
                  "name" : "orient"
                }
              }
            }
          }
        }
    }'

1. The `join` query clause.

2. The source indices (that is `companies`).

3. The clause specifying the paths for join keys in both source and target indices.

4. The search request that will be used to filter out companies.

The command should return you the following response with two search hits:

    {
      "hits" : {
        "total" : 2,
        "max_score" : 1.0,
        "hits" : [ {
          "_index" : "articles",
          "_type" : "article",
          "_id" : "1",
          "_score" : 1.0,
          "_source":{ "title" : "The NoSQL database glut", "mentions" : ["1", "2"] }
        }, {
          "_index" : "articles",
          "_type" : "article",
          "_id" : "3",
          "_score" : 1.0,
          "_source":{ "title" : "How to determine which NoSQL DBMS best fits your needs", "mentions" : ["2", "4"] }
        } ]
      }
    }

You can also reverse the order of the join, and query for all the companies that are mentioned in articles whose title matches `nosql`:

    $ curl -H 'Content-Type: application/json' 'http://localhost:9200/siren/companies/_search?pretty' -d '{
       "query" : {
          "join" : {
            "indices" : ["articles"],
            "on": ["id", "mentions"],
            "request" : {
              "query" : {
                "term" : {
                  "title" : "nosql"
                }
              }
            }
          }
        }
    }'

The command should return you the following response with three search hits:

    {
      "hits" : {
        "total" : 3,
        "max_score" : 1.0,
        "hits" : [ {
          "_index" : "companies",
          "_type" : "company",
          "_id" : "4",
          "_score" : 1.0,
          "_source":{ "id": "4", "name" : "MapR" }
        }, {
          "_index" : "companies",
          "_type" : "company",
          "_id" : "1",
          "_score" : 1.0,
          "_source":{ "id": "1", "name" : "Elastic" }
        }, {
          "_index" : "companies",
          "_type" : "company",
          "_id" : "2",
          "_score" : 1.0,
          "_source":{ "id": "2", "name" : "Orient Technologies" }
        } ]
      }
    }

## Search results

No results found

- Prev
- Next