Table of documentation contents

Quick start guide

This quick start guide will give you a 10-minute tour of Weaviate. You will:

  • Set up your Weaviate with Docker.
  • Add a example dataset with news articles.
  • Browse through the dataset with the Weaviate Playground.

Index

Run Weaviate with a demo dataset

There are many different ways how you can run Weaviate, from local development setups up to large scale Kubernetes environments or hosted and managed Weaviate clusters. For this quick start guide we will be using the Docker Compose setup where you can run Weaviate on your local machine to which we will add the demo dataset.

Docker Compose setup

Take the following steps:

  1. Follow one of the installation steps outlined here. Tip: the easiest way is to use the Docker Compose setup.
  2. If the import is finished, you are all set for the next step.

Validate via the RESTful API

You will always use Weaviate via its HTTP API interface. The interface consists of two different interfaces:

  • The RESTful API, which is mostly used to add and manipulate data.
  • The GraphQL API (which also runs over HTTP) to query data.

We will first check if Weaviate runs correctly, if the schema is added successfully, and if the data is available. In the example below, we will show you how to do it from the command line with jq.

First, we want to check if Weaviate is running correctly by inspecting the /v1/meta endpoint.

Note: make sure to replace $WEAVIATE with the location of your Weaviate.

$ curl -s http://$WEAVIATE/v1/meta | jq .

The output will look something like this:

{
  "contextionaryVersion": "en0.8.0-v0.3.3",
  "contextionaryWordCount": 211170,
  "hostname": "http://[::]:8080",
  "version": "0.22.1"
}

This validates that your Weaviate is running correctly.

Next, we want to check if the news publication schema was added correctly, you can do this by inspecting the /v1/schema endpoint.

$ curl -s http://$WEAVIATE/v1/schema | jq .

The output will look something like this but significantly longer:

{
  "actions": {
    "classes": [],
    "type": "action"
  },
  "things": {
    "classes": [
      {
        "class": "Publication",
        "description": "A publication with an online source",
        "properties": [
          {
            "cardinality": "atMostOne",
            "dataType": [
              "string"
            ],
            "description": "Name of the publication",
            "name": "name"
          },
          {
            "cardinality": "many",
            "dataType": [
              "Article"
            ],
            "description": "The articles this publication has",
            "name": "hasArticles"
          }
        ]
      }
    ]
  }
}

You should be able to identify three classes: Publication, Author and, Article.

Lastly, we will validate if all data was added correctly, we will do this via the /v1/things endpoint.

$ curl -s http://$WEAVIATE/v1/things | jq .

The output will look something like this but significantly longer:

{
    "things": [
        {
            "class": "Article",
            "creationTimeUnix": 1573143373633,
            "id": "02c4dc2b-6941-3a77-a54d-5f51a1926d22",
            "lastUpdateTimeUnix": 1573143373633,
            "schema": {
                "hasAuthors": [
                    {
                        "beacon": "weaviate://localhost/things/75479bb9-5871-3395-b49d-eb6037fb8082"
                    },
                    {
                        "beacon": "weaviate://localhost/things/dedd462a-23c8-32d0-9412-6fcf9c1e8149"
                    }
                ],
                "inPublication": [
                    {
                        "beacon": "weaviate://localhost/things/7e9b9ffe-e645-302d-9d94-517670623b35"
                    }
                ],
                "summary": "The result is a movie of a cynicism so vast and pervasive as to render the viewing experience even emptier than its slapdash aesthetic does. In between these two events, Arthur is seated on a city bus that’s crowded with passengers. In “Joker,” Arthur is quickly seen to be mentally ill, and he knows it—he takes seven medications and wants more. “Joker” is a wannabe movie that also wants to be all things to all viewers, that imitates the notion of adding substance while only subtracting it. “Joker” is a viewing experience of a rare, numbing emptiness.",
                "title": "“Joker” Is a Viewing Experience of Rare, Numbing Emptiness",
                "url": "https://www.newyorker.com/culture/the-front-row/joker-is-a-viewing-experience-of-rare-numbing-emptiness",
                "wordCount": 1794
            }
        }
    ]
}

Query the dataset with GraphQL

When querying Weaviate, you will always be using the GraphQL API. Weaviate has a publicly available graphical user interface (GUI) called The Playground, which you can use to query.

Accessing the Playground

Go to: playground.semi.technology Fill in the following URL: https://{YOUR WEAVIATE HOST}/v1/graphql as the endpoint. Click on the “GraphQL Querying” in the right top.

Your First Query

Let’s first get all news publications out.

# GraphQL
{
  Get {
    Things {
      Publication {
        name
      }
    }
  }
}

🟢 Click here to try out this graphql example in the Weaviate Playground.

You can also find which articles are related to these publications.

# GraphQL
{
  Get {
    Things {
      Publication {
        name
        HasArticles{
          ... on Article{
            title
          }
        }
      }
    }
  }
}

🟢 Click here to try out this graphql example in the Weaviate Playground.

And you can even go deeper, to find which authors are related to these publiations.

# GraphQL
{
  Get {
    Things {
      Publication(limit: 3) {
        name
        HasArticles{
          ... on Article{
            title
            HasAuthors {
              ... on Author{
                name
              }
            }
          }
        }
      }
    }
  }
}

🟢 Click here to try out this graphql example in the Weaviate Playground.

When querying for articles, you can also add classic filters to narrow down your search.

# GraphQL
{
  Get {
    Things {
      Article(
        where:{
          operator: GreaterThanEqual
          path: ["wordCount"]
          valueInt: 1000
        }
        limit: 10
      ) {
        title
        summary
        wordCount
      }
    }
  }
}

🟢 Click here to try out this graphql example in the Weaviate Playground.

Do you want to know how many articles, authors and publications there are? This is something you can find using the Aggregate{} function.

# GraphQL
{
  Aggregate{
    Things{
      Publication{
        meta{
          count
        }
      }
      Author{
        meta{
          count
        }
      }
      Article{
        meta{
          count
        }
        wordCount {
          count
          maximum
          mean
          median
          minimum
          mode
          sum
          type
        }
      }
    }
  }
}

🟢 Click here to try out this graphql example in the Weaviate Playground.

Explore the smart graph

In Weaviate, you can also semantically explore your datasets. Let’s search for articles related to money.

# GraphQL
{
  Get {
    Things {
      Article(
        explore: {
          concepts: ["money"]
        }
        limit: 10
      ) {
        title
        summary
      }
    }
  }
}

🟢 Click here to try out this graphql example in the Weaviate Playground.

You can also combine filters!

# GraphQL
{
  Get {
    Things {
      Article(
        explore: {
          concepts: ["rideSharing"]
        }
        where:{ 
          operator:And
          operands: [{
            operator: GreaterThan
            path: ["wordCount"]
            valueInt: 200
          }, {
            operator:Like
            path:["title"]
            valueString:"*tax*"
          }]
        }
        limit: 10
      ) {
        title
        summary
        wordCount
      }
    }
  }
}

🟢 Click here to try out this graphql example in the Weaviate Playground.

Or group similar topics semantically together.

Tip: play around with the force variable.

# GraphQL
{
  Get {
    Things {
      Publication(
       	group: {
          type: merge
          force: 0.05
        }
      ) {
        name
      }
    }
  }
}

🟢 Click here to try out this graphql example in the Weaviate Playground.

Automatic Classification

If you run the following query, you might notice that there are no categories classified for articles.

# GraphQL
{
  Get {
    Things {
      Article {
        title
        OfCategory {
          ... on Category {
            name
          }
        }
      }
    }
  }
}

🟢 Click here to try out this graphql example in the Weaviate Playground.

Here we can use Weaviate’s auto-classification function to let Weaviate decide which categories to attach to news publications.

To do this, we will use the RESTful API.

$ curl https://{YOUR WEAVIATE HOST}/v1/classifications -X POST -H 'Content-type: application/json' -d \
'{
    "class": "Article",
    "type": "contextual",
    "basedOnProperties": [
        "summary"
    ],
    "classifyProperties": [
        "ofCategory"
    ]
}' | jq .

When Weaviate is done with the classification, you can rerun the previous query and see how Weaviate classified all articles.

# GraphQL
{
  Get {
    Things {
      Article {
        title
        OfCategory {
          ... on Category {
            name
          }
        }
      }
    }
  }
}

🟢 Click here to try out this graphql example in the Weaviate Playground.

By using the RESTful API, you can even get statistics related to the classification.

$ curl -k https://{YOUR WEAVIATE HOST}/v1/things/{CLASSIFICATION ID}?meta=true | jq .

This was a sneak peek of Weaviate. In the documentation, you can find more videos and guides on how to work with Weaviate in depth.

Have fun building your own smart graph with Weaviate!

More Resources

If you can’t find the answer to your question here, please use the:

  1. Knowledge base of old issues. Or,
  2. For questions: Stackoverflow. Or,
  3. For issues: Github.
  4. For Frequently Asked Questions.
Tags
  • introduction
  • Weaviate
  • Contextionary