Store and Access Data #

Now that Kuzzle is running, we are going to create some documents.

Kuzzle organizes the data storage in 4 levels:

• Indexes
• Collections
• Documents
• Fields

An index brings together several collections, which in turn contain several documents, each of which is composed of several fields.

The collections have mappings that define the way Elasticsearch will index the data for searches.

By default Elasticsearch will try to infer the type of the fields introduced by documents.
It is recommended that you define your own mappings in order to specify the desired types for your collections and avoid default types that may be imprecise. Learn more about mappings dynamic policy

If you're more familiar with the way relational databases store data, here is an analogy. Bear in mind that this is only to give you a rough point of comparison with a relational database, the similarities end here:

Relational databases storage	Document-oriented storage
database	index
table	collection
schema	mappings
line	document
column	field

Kuzzle uses Elasticsearch as a NoSQL document storage.
Elasticsearch is primarily designed to be a search engine, so there are limitations when using it as a database.
Learn more about those limitations in our in-depth guides: Collection Mappings and Querying Elasticsearch

Prepare the database #

First, we are going to create an index with Kourou: kourou index:create nyc-open-data

This will use the index:create API action.

Then, we are going to create a collection inside this index. We will provide the following basic mappings:

Copied to clipboard!

{
  properties: {
    name: { type: "keyword" },
    city: { type: "keyword" },
    age: { type: "integer" }
  }
}

Run the following command to create our yellow-taxi collection:

Copied to clipboard!

kourou collection:create nyc-open-data yellow-taxi '{
  mappings: {
    properties: {
      name: { type: "keyword" },
      city: { type: "keyword" },
      age: { type: "integer" }
    }
  }
}'

This will use the collection:create API action.

Create some documents #

Now we have a collection ready to receive documents, again use Kourou to create one:

Copied to clipboard!

kourou document:create nyc-open-data yellow-taxi '{
  name: "Melis",
  city: "Istanbul",
  age: 25
}'

This will use the document:create API action.

Finally, we are going to use the Admin Console to look at what we have created.

Select the nyc-open-data index and then the yellow-taxi collection. You should see one document in this collection.

Search for documents #

Kuzzle allows to search for documents through its API, with different query languages depending on your needs.

We'll now use that to search for the documents we're interested in.

First, we need to create more documents:

Copied to clipboard!

kourou sdk:execute '
  for (let i = 1; i <= 10; i++) {
    await sdk.document.create("nyc-open-data", "yellow-taxi", {
      name: `Melis-${i}`,
      city: i % 2 ? "Antalya" : "Istanbul",
      age: 25 + i
    });
  }'

Kourou is able to execute Javascript code snippets.
A sdk variable is exposed and refers to an instance of the Javascript SDK, connected to Kuzzle and authenticated if credentials are provided.

Then we are going to use the document:search API action to fetch only documents where:

• age is greater than 30
• city is equal to Antalya

For this, we need to write a Koncorde Query:

Copied to clipboard!

{
  and: [
    {
      range: {
        age: { gt: 30 }
      }
    },
    {
      equals: { city: "Antalya" }
    }
  ]
}

And to execute this query we are going to use Kourou again:

Copied to clipboard!

kourou document:search nyc-open-data yellow-taxi '{
  and: [
    {
      range: {
        age: { gt: 30 }
      }
    },
    {
      equals: { city: "Antalya" }
    }
  ]
}'

You should retrieve the following 2 documents:

Copied to clipboard!

 🚀 Kourou - Searches for documents
 
 [ℹ] Connecting to http://localhost:7512 ...
 [ℹ] Document ID: OYgZJnUBacNMjDl2504F
 Content: {
  "name": "Melis-7",
  "city": "Antalya",
  "age": 32,
  "_kuzzle_info": {
    "author": "-1",
    "createdAt": 1602662033156,
    "updatedAt": null,
    "updater": null
  }
}
 [ℹ] Document ID: O4gZJnUBacNMjDl2504n
 Content: {
  "name": "Melis-9",
  "city": "Antalya",
  "age": 34,
  "_kuzzle_info": {
    "author": "-1",
    "createdAt": 1602662033189,
    "updatedAt": null,
    "updater": null
  }
}
[✔] 2 documents fetched on a total of 2

◄ Run Kuzzle Set up Permissions ►