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 thenearText
filter in theGet{}
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 athttp://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 classesPublication
,Article
andAuthor
. - 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 ofPublication
s,Article
s andAuthor
s 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 Publication
s that are related to “fashion”, we can do the following query:
{
Get{
Publication(
nearText: {
concepts: ["fashion"],
certainty: 0.7,
moveAwayFrom: {
concepts: ["finance"],
force: 0.45
},
moveTo: {
concepts: ["haute couture"],
force: 0.85
}
}
){
name
}
}
}
import weaviate
client = weaviate.Client("http://localhost:8080")
get_articles_query = """
{
Get{
Publication(
nearText: {
concepts: ["fashion"],
certainty: 0.7,
moveAwayFrom: {
concepts: ["finance"],
force: 0.45
},
moveTo: {
concepts: ["haute couture"],
force: 0.85
}
}
){
name
}
}
}
"""
query_result = client.query.raw(get_articles_query)
print(query_result)
const weaviate = require("weaviate-client");
const client = weaviate.client({
scheme: 'http',
host: 'localhost:8080',
});
client.graphql
.get()
.withClassName('Publication')
.withFields('name')
.withNearText({
concepts: ["fashion"],
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).
WithCertainty(0.7).
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)
}
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)
.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());
}
}
$ echo '{
"query": "{
Get{
Publication(
nearText: {
concepts: [\"fashion\"],
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”.
{
Explore (
nearText: {
concepts: ["fashion"],
certainty: 0.7,
moveTo: {
concepts: ["haute couture"],
force: 0.45
},
moveAwayFrom: {
concepts: ["finance"],
force: 0.85
}
}
) {
beacon
certainty
className
}
}
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)
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)
}
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());
}
}
$ 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/{id}
So querying all property values of the first result can be done as follows:
$ curl -s http://localhost:8080/v1/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.