How to perform a semantic search?

How to perform a semantic search in Weaviate?

Introduction

Weaviate has RESTful API endpoints to query data, but Weaviate’s query language is GraphQL.
You can query a Weaviate after you’ve created a schema and populated it with data.
You can perform simple Get{} queries to easily retrieve data, learn how here.
To narrow down search results from a Get{} query based on semantics, use the nearText filter in the Get{} query. Read how in this tutorial.
To search and find for data objects in a fuzzy manner, you can use the GraphQL Explore{} function, read how in this tutorial, and on the reference page.

Prerequisites

Connect to a Weaviate instance.
If you haven’t set up a Weaviate instance yet, check the Getting started guide. In this guide we assume your instance is running at http://localhost:8080 with text2vec-contextionary as vectorization module.
Upload a schema.
Learn how to create and upload a schema here. In this guide we assume to have a similar schema uploaded with the classes Publication, Article and Author.
Add data.
Make sure there is data available in your Weaviate instance, you can read how to do this in the previous guide. In this tutorial we assume there are data objects of Publications, Articles and Authors present.

nearText filter

If you want to perform semantic search on data objects in a known class, you can use the nearText filter in a Get{} query. Let’s say we want to find Publications that are related to “fashion”, we can do the following query:

GraphQL

  {
  Get{
    Publication(
      nearText: {
        concepts: ["fashion"],
        distance: 0.6, # prior to v1.14 use certainty: 0.7,
        moveAwayFrom: {
          concepts: ["finance"],
          force: 0.45
        },
        moveTo: {
          concepts: ["haute couture"],
          force: 0.85
        }
      }
    ){
      name
    }
  }
}

Python

  import weaviate

client = weaviate.Client("http://localhost:8080")

where_filter = {
  'concepts': ["fashion"],
  'distance': 0.6, # prior to v1.14 use 'certainty': 0.7,
  'moveAwayFrom': {
    'concepts': ["finance"],
    'force': 0.45
  },
  'moveTo': {
    'concepts': ["haute couture"],
    'force': 0.85
  }
}

query_result = client.query.raw(get_articles_query)

query_result = (
  client.query
  .get('Publication', 'name')
  .with_where(where_filter)
  .do()
)

print(query_result)

Javascript

  const weaviate = require("weaviate-client");

const client = weaviate.client({
  scheme: 'http',
  host: 'localhost:8080',
});

client.graphql
      .get()
      .withClassName('Publication')
      .withFields('name')
      .withNearText({
        concepts: ["fashion"],
        distance: 0.6, # prior to v1.14 use certainty: 0.7,
        moveAwayFrom: {
          concepts: ["finance"],
          force: 0.45
        },
        moveTo: {
          concepts: ["haute couture"],
          force: 0.85
        }
      })
      .do()
      .then(res => {
        console.log(res)
      })
      .catch(err => {
        console.error(err)
      });

  package main

import (
  "context"
  "fmt"

  "github.com/semi-technologies/weaviate-go-client/v4/weaviate"
  "github.com/semi-technologies/weaviate-go-client/v4/weaviate/graphql"
)

func main() {
  cfg := weaviate.Config{
    Host:   "localhost:8080",
    Scheme: "http",
  }
  client := weaviate.New(cfg)

  className := "Publication"
  name := graphql.Field{Name: "name"}

  concepts := []string{"fashion"}
  moveTo := &graphql.MoveParameters{
    Concepts: []string{"haute couture"},
    Force:    0.85,
  }
  moveAwayFrom := &graphql.MoveParameters{
    Concepts: []string{"finance"},
    Force:    0.45,
  }
  nearText := client.GraphQL().NearTextArgBuilder().
    WithConcepts(concepts).
    WithDistance(0.6). // prior to v1.14 use WithCertainty(0.6)
    WithMoveTo(moveTo).
    WithMoveAwayFrom(moveAwayFrom)

  ctx := context.Background()

  result, err := client.GraphQL().Get().
    WithClassName(className).
    WithFields(name).
    WithNearText(nearText).
    Do(ctx)

  if err != nil {
    panic(err)
  }
  fmt.Printf("%v", result)
}

Java

  package technology.semi.weaviate;

import technology.semi.weaviate.client.Config;
import technology.semi.weaviate.client.WeaviateClient;
import technology.semi.weaviate.client.base.Result;
import technology.semi.weaviate.client.v1.graphql.model.GraphQLResponse;
import technology.semi.weaviate.client.v1.graphql.query.argument.NearTextArgument;
import technology.semi.weaviate.client.v1.graphql.query.argument.NearTextMoveParameters;
import technology.semi.weaviate.client.v1.graphql.query.fields.Field;

public class App {
  public static void main(String[] args) {
    Config config = new Config("http", "localhost:8080");
    WeaviateClient client = new WeaviateClient(config);

    NearTextMoveParameters moveTo = NearTextMoveParameters.builder()
      .concepts(new String[]{ "haute couture" }).force(0.85f).build();

    NearTextMoveParameters moveAway = NearTextMoveParameters.builder()
      .concepts(new String[]{ "finance" }).force(0.45f)
      .build();

    Field name = Field.builder().name("name").build();

    NearTextArgument nearText = client.graphQL().arguments().nearTextArgBuilder()
      .concepts(new String[]{ "fashion" })
      .moveTo(moveTo)
      .moveAwayFrom(moveAway)
      .distance(0.6f) // prior to v1.14 use .certainty(0.7f)
      .build();

    Result<GraphQLResponse> result = client.graphQL().get()
      .withClassName("Publication")
      .withFields(name)
      .withNearText(nearText)
      .run();

    if (result.hasErrors()) {
      System.out.println(result.getError());
      return;
    }
    System.out.println(result.getResult());
  }
}

curl

  $ echo '{ 
    "query": "{
      Get{
        Publication(
          nearText: {
            concepts: [\"fashion\"],
            distance: 0.6, # prior to v1.14 use certainty: 0.7,
            moveAwayFrom: {
              concepts: [\"finance\"],
              force: 0.45
            },
            moveTo: {
              concepts: [\"haute couture\"],
              force: 0.85
            }
          }
        ){
          name
        }
      }
    }"
  }' | curl \
      -X POST \
      -H 'Content-Type: application/json' \
      -d @- \
      http://localhost:8080/v1/graphql

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

This will result in something like the following. Vogue was selected as only result, because there were no other publications related enough to “fashion” and “haute couture”.

{
  "data": {
    "Get": {
      "Things": {
        "Publication": [
          {
            "name": "Vogue"
          }
        ]
      }
    }
  },
  "errors": null
}

Explore GraphQL function

If you are not sure what classes you want to query, or want to perform a fuzzy search through your whole dataset, then you can use the Explore{} function instead of the Get{} function. In the Explore{} function you don’t specify which classes you perform the semantic search on, so the semantic search will be performed on all the data objects. Since this search is fuzzy, the only fields you can return are the beacon, certainty, className; you cannot request property values of the data objects, since the property value names depend on the data object, defined in the schema.

Let’s search for data object about fashion again, but now we are not only interested in Publication data objects, but in all data objects that have something to do with “fashion”.

GraphQL

  {
  Explore (
    nearText: {
      concepts: ["fashion"],
      certainty: 0.7,
      moveTo: {
        concepts: ["haute couture"],
        force: 0.45
      },
      moveAwayFrom: {
        concepts: ["finance"],
        force: 0.85
      }
    }
  ) {
    beacon
    certainty
    className
  }
}

Python

  import weaviate

client = weaviate.Client("http://localhost:8080")

get_articles_query = """
  {
    Explore (
      nearText: {
        concepts: [\"fashion\"],
        certainty: 0.7,
        moveTo: {
          concepts: [\"haute couture\"],
          force: 0.45
        },
        moveAwayFrom: {
          concepts: [\"finance\"],
          force: 0.85
        }
      }
    ) {
      beacon
      certainty
      className
    }
  }
"""

query_result = client.query.raw(get_articles_query)
print(query_result)

Javascript

  const weaviate = require("weaviate-client");

const client = weaviate.client({
  scheme: 'http',
  host: 'localhost:8080',
});

client.graphql
      .explore()
      .withNearText({concepts:['fashion'], moveTo: {concepts: ['haute couture'], force: 0.85}, moveAwayFrom: {concepts: ['finance'], force: 0.45})})
      .withCertainty(0.7)
      .withFields('beacon certainty className')
      .do()
      .then(res => {
        console.log(res)
      })
      .catch(err => {
        console.error(err)
      });

  package main

import (
  "context"
  "fmt"

  "github.com/semi-technologies/weaviate-go-client/v4/weaviate"
  "github.com/semi-technologies/weaviate-go-client/v4/weaviate/graphql"
)

func main() {
  cfg := weaviate.Config{
    Host:   "localhost:8080",
    Scheme: "http",
  }
  client := weaviate.New(cfg)

  concepts := []string{"fashion"}
  moveTo := &graphql.MoveParameters{
    Concepts: []string{"haute couture"},
    Force:    0.5,
  }
  moveAwayFrom := &graphql.MoveParameters{
    Concepts: []string{"finance"},
    Force:    0.2,
  }

  withNearText := client.GraphQL().NearTextArgBuilder().
    WithConcepts(concepts).
    WithCertainty(0.7).
    WithMoveTo(moveTo).
    WithMoveAwayFrom(moveAwayFrom)

  result, err := client.GraphQL().Explore().
    WithFields(graphql.Certainty, graphql.Beacon, graphql.ClassName).
    WithNearText(withNearText).
    Do(context.Background())

  if err != nil {
    panic(err)
  }
  fmt.Printf("%v", result)
}

Java

  package technology.semi.weaviate;

import technology.semi.weaviate.client.Config;
import technology.semi.weaviate.client.WeaviateClient;
import technology.semi.weaviate.client.base.Result;
import technology.semi.weaviate.client.v1.graphql.model.ExploreFields;
import technology.semi.weaviate.client.v1.graphql.model.GraphQLResponse;
import technology.semi.weaviate.client.v1.graphql.query.argument.NearTextArgument;
import technology.semi.weaviate.client.v1.graphql.query.argument.NearTextMoveParameters;

public class App {
  public static void main(String[] args) {
    Config config = new Config("http", "localhost:8080");
    WeaviateClient client = new WeaviateClient(config);

    NearTextMoveParameters moveTo = NearTextMoveParameters.builder()
      .concepts(new String[]{ "haute couture" }).force(0.45f).build();

    NearTextMoveParameters moveAway = NearTextMoveParameters.builder()
      .concepts(new String[]{ "finance" }).force(0.85f)
      .build();

    NearTextArgument nearText = client.graphQL().arguments().nearTextArgBuilder()
      .concepts(new String[]{ "fashion" })
      .moveTo(moveTo)
      .moveAwayFrom(moveAway)
      .certainty(0.7f)
      .build();

    Result<GraphQLResponse> result = client.graphQL().explore()
      .withFields(ExploreFields.CERTAINTY, ExploreFields.BEACON, ExploreFields.CLASS_NAME)
      .withNearText(nearText)
      .run();

    if (result.hasErrors()) {
      System.out.println(result.getError());
      return;
    }
    System.out.println(result.getResult());
  }
}

curl

  $ echo '{ 
    "query": "{
      Explore (
        nearText: {
          concepts: [\"fashion\"],
          certainty: 0.7,
          moveTo: {
            concepts: [\"haute couture\"],
            force: 0.45
          },
          moveAwayFrom: {
            concepts: [\"finance\"],
            force: 0.85
          }
        }
      ) {
        beacon
        certainty
        className
      }
    }"
  }' | curl \
      -X POST \
      -H 'Content-Type: application/json' \
      -d @- \
      http://localhost:8080/v1/graphql

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

As you can see, the same arguments are applied in the “explore” filter and the Explore{} function. There is however no class specified. Instead, the className is returned as one of the GraphQL fields. The result of this query contains both data objects from the class Publication and Article:

{
  "data": {
    "Explore": [
      {
        "beacon": "weaviate://localhost/65010df4-da64-333d-b1ce-55c3fc9174ab",
        "certainty": 0.8257073,
        "className": "Article"
      },
      {
        "beacon": "weaviate://localhost/ac884d35-ccb4-3937-81f8-8474a4d7a549",
        "certainty": 0.79948425,
        "className": "Publication"
      },
      {
        "beacon": "weaviate://localhost/f2b7c189-9183-3095-a5bb-b619d7fe9703",
        "certainty": 0.7862817,
        "className": "Article"
      },
      {
        "beacon": "weaviate://localhost/21239ca9-8f09-3747-b369-ff41e0dfebdd",
        "certainty": 0.7857753,
        "className": "Article"
      },
      {
        "beacon": "weaviate://localhost/8f2cb04e-c3bb-344f-8fbd-f742bf36e653",
        "certainty": 0.77738225,
        "className": "Article"
      }
    ]
  },
  "errors": null
}

If you are interested in property values of the returned objects, you will need to do a second query to to retrieve data of the beacon:

$ curl -s http://localhost:8080/v1/objects/{id}

So querying all property values of the first result can be done as follows:

$ curl -s http://localhost:8080/v1/objects/65010df4-da64-333d-b1ce-55c3fc9174ab

Next steps

Look for more ways to query your dataset in Weaviate with GraphQL queries, semantic search and other filters in the GraphQL references guide.
Stay tuned for new tutorials, for example on interpretation of the semantic search results or how to set up a classification model!

More resources

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

Frequently Asked Questions. Or,
Knowledge base of old issues. Or,
For questions: Stackoverflow. Or,
For issues: Github. Or,
Ask your question in the Slack channel: Slack.

Edit on Github

Introduction
Prerequisites
nearText filter
Explore GraphQL function
Next steps
More resources

weaviate

Core Knowledge

Getting started

Installation

Configuration

Client libraries

Schema

GraphQL references

RESTful API references

Modules

Retrievers & Vectorizers

Readers & Generators

Other Modules

Roadmap

Architecture

Vector Index (ANN) Plugins

Benchmarks

Tutorials

More resources

How to perform a semantic search?

Introduction

Prerequisites

nearText filter

Explore GraphQL function

Next steps

More resources

Table of Contents

More resources?

Meetups

All Resources

Blog

Podcast

Newsletter

Documentation

Contributor Guide

Weaviate Cloud Service

Github

Slack

weaviate

Retrievers & Vectorizers

Readers & Generators

Other Modules

How to perform a semantic search?

Introduction

Prerequisites

nearText filter

Explore GraphQL function

Next steps

More resources

Table of Contents