Search patterns and basics

With Weaviate you can query your data using vector similarity search, keyword search, or a mix of both with hybrid search. You can control what object properties and metadata to return.

This page provides fundamental search syntax to get you started.

List objects

You can get objects without specifying any parameters. This returns objects in ascending UUID order.

Python Client v4

jeopardy = client.collections.get("JeopardyQuestion")
response = jeopardy.query.fetch_objects()

for o in response.objects:
    print(o.properties)

Python Client v3

response = client.query.get("JeopardyQuestion", ["question"]).do()

print(response)

JS/TS Client v3

const myCollection = client.collections.get('JeopardyQuestion');

const result = await myCollection.query.fetchObjects()
console.log(JSON.stringify(result, null, 2));

JS/TS Client v2

result = await client
  .graphql
  .get()
  .withClassName('JeopardyQuestion')
  .withFields('question')
  .do();

console.log(JSON.stringify(result, null, 2));

Go

response, err := client.GraphQL().Get().
  WithClassName("JeopardyQuestion").
  WithFields(graphql.Field{Name: "question"}).
  Do(ctx)

Java

Result<List<WeaviateObject>> resultObj = client.data().objectsGetter()
  .withClassName(className)
  .run();

GraphQL

{
  Get {
    JeopardyQuestion {
      question
    }
  }
}

Example response

The output is like this:

{
  "data": {
    "Get": {
      "JeopardyQuestion": [
        {
          "question": "This prophet passed the time he spent inside a fish offering up prayers"
        },
        // shortened for brevity
      ]
    }
  }
}

Additional information

Specify the information that you want your query to return. You can return object properties, object IDs, and object metadata.

limit returned objects

Use limit to set a fixed maximum number of objects to return.

Python Client v4

jeopardy = client.collections.get("JeopardyQuestion")
response = jeopardy.query.fetch_objects(
    limit=1
)

for o in response.objects:
    print(o.properties)

Python Client v3

response = (
    client.query.get("JeopardyQuestion", ["question"])
    .with_limit(1)
    .do()
)

print(response)

JS/TS Client v3

const myCollection = client.collections.get('JeopardyQuestion');

const result = await myCollection.query.fetchObjects(
  { limit: 1 }
)
     
console.log(JSON.stringify(result, null, 2));

JS/TS Client v2

result = await client
  .graphql
  .get()
  .withClassName('JeopardyQuestion')
  .withFields('question')
  .withLimit(1)
  .do();

console.log(JSON.stringify(result, null, 2));

Go

response, err := client.GraphQL().Get().
  WithClassName("JeopardyQuestion").
  WithFields(graphql.Field{Name: "question"}).
  WithLimit(1).
  Do(ctx)

Java

Result<List<WeaviateObject>> resultObj = client.data().objectsGetter()
  .withClassName(className)
  .withLimit(1) // Object IDs are included by default with the Java client
  .run();

GraphQL

{
  Get {
    JeopardyQuestion (
      limit: 1
    ) {
      question
    }
  }
}

Example response

The output is like this:

{
  "data": {
    "Get": {
      "JeopardyQuestion": [
        {
          "question": "This prophet passed the time he spent inside a fish offering up prayers"
        },
        // Note this will only have one result as we limited it to 1
      ]
    }
  }
}

Paginate with limit and offset

To start in the middle of your result set, define an offset. Set a limit to return objects starting at the offset.

Python Client v4

jeopardy = client.collections.get("JeopardyQuestion")
response = jeopardy.query.fetch_objects(
    limit=1,
    offset=1
)

for o in response.objects:
    print(o.properties)

Python Client v3

response = (
    client.query.get("JeopardyQuestion", ["question"])
    .with_limit(1).with_offset(1)
    .do()
)

print(response)

JS/TS Client v3

const myCollection = client.collections.get('JeopardyQuestion');

const result = await myCollection.query.fetchObjects({
  limit: 1,
  offset: 1,
})

console.log(JSON.stringify(result, null, 2));

JS/TS Client v2

result = await client
  .graphql
  .get()
  .withClassName('JeopardyQuestion')
  .withFields('question')
  .withLimit(1)
  .withOffset(1)
  .do();

console.log(JSON.stringify(result, null, 2));

Go

response, err := client.GraphQL().Get().
  WithClassName("JeopardyQuestion").
  WithFields(graphql.Field{Name: "question"}).
  WithLimit(1).
  WithOffset(1).
  Do(ctx)

Java

Result<List<WeaviateObject>> resultObj = client.data().objectsGetter()
  .withClassName(className)
  .withLimit(1)
  .withOffset(1)
  .run();

GraphQL

{
  Get {
    JeopardyQuestion (
      limit: 1
      offset: 1
    ) {
      question
    }
  }
}

Example response

The output is like this:

{
  "data": {
    "Get": {
      "JeopardyQuestion": [
        {
          "question": "Pythons are oviparous, meaning they do this"
        }
      ]
    }
  }
}

To paginate through the entire database, use a cursor instead of offset and limit.

Specify object properties

You can specify which object properties to return.

Python Client v4

jeopardy = client.collections.get("JeopardyQuestion")
response = jeopardy.query.fetch_objects(
    limit=1,
    return_properties=["question", "answer", "points"]
)

for o in response.objects:
    print(o.properties)

Python Client v3

response = (
    client.query
    .get("JeopardyQuestion", ["question", "answer", "points"])
    .with_limit(1).do()
)

print(response)

JS/TS Client v3

const myCollection = client.collections.get('JeopardyQuestion');

const result = await myCollection.query.fetchObjects({
  limit: 1,
  returnProperties: ['question', 'answer', 'points'],
})

console.log(JSON.stringify(result, null, 2));

JS/TS Client v2

result = await client
  .graphql
  .get()
  .withClassName('JeopardyQuestion')
  .withFields('question answer points')
  .withLimit(1)
  .do();

console.log(JSON.stringify(result, null, 2));

Go

response, err := client.GraphQL().Get().
  WithClassName("JeopardyQuestion").
  WithFields(
  	graphql.Field{Name: "question"},
  	graphql.Field{Name: "answer"},
  	graphql.Field{Name: "points"},
  ).
  WithLimit(1).
  Do(ctx)

Java

Result<List<WeaviateObject>> resultObj = client.data().objectsGetter()
  .withClassName(className)
  .withLimit(1)
  .run();
resultObj.getResult().get(0).getProperties().get(propertyName);

GraphQL

{
  Get {
    JeopardyQuestion (limit: 1) {
      question
      answer
      points
    }
  }
}

Example response

The output is like this:

{
  "data": {
    "Get": {
      "JeopardyQuestion": [
        {
          "answer": "Jonah",
          "points": 100,
          "question": "This prophet passed the time he spent inside a fish offering up prayers"
        },
      ]
    }
  }
}

Retrieve the object vector

You can retrieve the object vector. (Also applicable where named vectors are used.)

Python Client v4

jeopardy = client.collections.get("JeopardyQuestion")
response = jeopardy.query.fetch_objects(
    include_vector=True,
    limit=1
)

print(response.objects[0].vector["default"])

Python Client v3

response = (
    client.query.get("JeopardyQuestion")
    .with_additional("vector")
    .with_limit(1).do()
)

print(response)

JS/TS Client v3

const myCollection = client.collections.get('JeopardyQuestion');

const result = await myCollection.query.fetchObjects({
  includeVector: true,
  limit: 1,

})

console.log(JSON.stringify(result, null, 2));

JS/TS Client v2

result = await client
  .graphql
  .get()
  .withClassName('JeopardyQuestion')
  .withFields('_additional {vector}')
  .withLimit(1)
  .do();

console.log(JSON.stringify(result, null, 2));

Go

response, err := client.GraphQL().Get().
  WithClassName("JeopardyQuestion").
  WithFields(
  	graphql.Field{
  		Name: "_additional",
  		Fields: []graphql.Field{
  			{Name: "vector"},
  		},
  	},
  ).
  WithLimit(1).
  Do(ctx)

Java

Result<List<WeaviateObject>> resultObj = client.data().objectsGetter()
  .withClassName(className)
  .withLimit(1)
  .withVector()
  .run();

GraphQL

{
  Get {
    JeopardyQuestion (limit: 1) {
      _additional {
        vector
      }
    }
  }
}

Example response

The output is like this:

{
  "data": {
    "Get": {
      "JeopardyQuestion": [
        {
          "_additional": {
            "vector": [
              0.0065065133,
              -0.017786196,
              0.005879146,
              0.006707012,
              ...  // shortened for brevity
            ]
          }
        },
      ]
    }
  }
}

Retrieve the object id

You can retrieve the object id (uuid).

Python Client v4

jeopardy = client.collections.get("JeopardyQuestion")
response = jeopardy.query.fetch_objects(
    # Object IDs are included by default with the `v4` client! :)
    limit=1
)

for o in response.objects:
    print(o.uuid)

Python Client v3

response = (
    client.query.get("JeopardyQuestion")
    .with_additional("id")
    .with_limit(1).do()
)

print(response)

JS/TS Client v3

const myCollection = client.collections.get('JeopardyQuestion');

const result = await myCollection.query.fetchObjects({
  // Object IDs are included by default with the `v3` client! :)
  limit: 1,
})

for (let object of result.objects) {
   console.log(JSON.stringify(object.uuid, null, 2));
}

JS/TS Client v2

result = await client
  .graphql
  .get()
  .withClassName('JeopardyQuestion')
  .withFields('_additional { id }')
  .withLimit(1)
  .do();

console.log(JSON.stringify(result, null, 2));

Go

response, err := client.GraphQL().Get().
  WithClassName("JeopardyQuestion").
  WithFields(
  	graphql.Field{
  		Name: "_additional",
  		Fields: []graphql.Field{
  			{Name: "id"},
  		},
  	},
  ).
  WithLimit(1).
  Do(ctx)

Java

Result<List<WeaviateObject>> resultObj = client.data().objectsGetter()
  .withClassName(className)
  .withLimit(1)
  .run();
resultObj.getResult().get(0).getId();

GraphQL

{
  Get {
    JeopardyQuestion (limit: 1) {
      _additional {
        id
      }
    }
  }
}

Example response

The output is like this:

{
  "data": {
    "Get": {
      "JeopardyQuestion": [
        {
          "_additional": {
            "id": "0002bf92-80c8-5d94-af34-0d6c5fea1aaf"
          }
        },
        // shortened for brevity
      ]
    }
  }
}

Retrieve cross-referenced properties

To retrieve properties from cross-referenced objects, specify:

• The cross-reference property
• The target cross-referenced collection
• The properties to retrieve

Python Client v4

from weaviate.classes.query import QueryReference

jeopardy = client.collections.get("JeopardyQuestion")
response = jeopardy.query.fetch_objects(
    return_references=[
        QueryReference(
            link_on="hasCategory",
            return_properties=["title"]
        ),
    ],
    limit=2
)

for o in response.objects:
    print(o.properties["question"])
    # print referenced objects
    for ref_obj in o.references["hasCategory"].objects:
        print(ref_obj.properties)

Python Client v3

response = (
    client.query
    .get(
        "JeopardyQuestion",
        ["question", "hasCategory { ... on JeopardyCategory { title } }"],
    )
    .with_limit(2).do()
)

print(json.dumps(response, indent=2))

JS/TS Client v3

const myCollection = client.collections.get('JeopardyQuestion');

const result = await myCollection.query.fetchObjects({
  limit: 2,
  returnReferences: [{
    linkOn: 'hasCategory',
    returnProperties: ['title'],
  }]
})

result.objects.forEach(item => 
  console.log(JSON.stringify(item.references, null, 2))
);

JS/TS Client v2

result = await client.graphql
  .get()
  .withClassName('JeopardyQuestion')
  .withFields(`
  question
  hasCategory {
    ... on JeopardyCategory {
      title
    }
  }`)
  .withLimit(2)
  .do();

console.log(JSON.stringify(result, null, 2));

Go

response, err := client.GraphQL().Get().
  WithClassName("JeopardyQuestion").
  WithFields(
  	graphql.Field{Name: "question"},
  	graphql.Field{
  		Name: "hasCategory",
  		Fields: []graphql.Field{
  			{Name: "... on JeopardyCategory", Fields: []graphql.Field{{Name: "title"}}},
  		},
  	},
  ).
  WithLimit(2).
  Do(ctx)

GraphQL

{
  Get {
    JeopardyQuestion (
      limit: 2
    )
    {
      question
      hasCategory {
        ... on JeopardyCategory {
          title
        }
      }
    }
  }
}

Example response

The output is like this:

    {
        "data": {
            "Get": {
                "JeopardyQuestion": [
                    {
                        "hasCategory": [{"title": "THE BIBLE"}],
                        "question": "This prophet passed the time he spent inside a fish offering up prayers",
                    },
                    {
                        "hasCategory": [{"title": "ANIMALS"}],
                        "question": "Pythons are oviparous, meaning they do this",
                    },
                ]
            }
        }
    }

Retrieve metadata values

You can specify metadata fields to be returned.

Python Client v4

from weaviate.classes.query import MetadataQuery

jeopardy = client.collections.get("JeopardyQuestion")
response = jeopardy.query.fetch_objects(
    limit=1,
    return_metadata=MetadataQuery(creation_time=True)
)

for o in response.objects:
    print(o.properties)  # View the returned properties
    print(o.metadata.creation_time)  # View the returned creation time

Python Client v3

response = (
    client.query.get("JeopardyQuestion", ["question"])
    .with_limit(1)
    .with_additional("creationTimeUnix")
    .do()
)

print(json.dumps(response, indent=2))

JS/TS Client v3

const myCollection = client.collections.get('JeopardyQuestion');

const result = await myCollection.query.fetchObjects({
  limit: 2,
  returnMetadata: ['creationTime', ]
})

for (let object of result.objects) {
  console.log(JSON.stringify(object.properties, null, 2));
  console.log(JSON.stringify(object.metadata?.creationTime, null, 2));
}

JS/TS Client v2

result = await client
  .graphql
  .get()
  .withClassName('JeopardyQuestion')
  .withLimit(1)
  .withFields('question _additional { creationTimeUnix }')
  .do();

console.log(JSON.stringify(result, null, 2));

Go

response, err := client.GraphQL().Get().
  WithClassName("JeopardyQuestion").
  WithLimit(1).
  WithFields(
  	graphql.Field{Name: "question"},
  	graphql.Field{
  		Name: "_additional",
  		Fields: []graphql.Field{
  			{Name: "creationTimeUnix"},
  		},
  	},
  ).
  Do(ctx)

Java

Result<List<WeaviateObject>> resultObj = client.data().objectsGetter()
  .withClassName(className)
  .run();
resultObj.getResult().get(0).getLastUpdateTimeUnix();
resultObj.getResult().get(0).getCreationTimeUnix();

GraphQL

{
  Get {
    JeopardyQuestion (
      limit: 1
    ) {
      question
      _additional { creationTimeUnix }
    }
  }
}

For a comprehensive list of metadata fields, see GraphQL: Additional properties.

Multi-tenancy

If multi-tenancy is enabled, specify the tenant parameter in each query.

Python Client v4

# Connect to the collection
mt_collection = client.collections.get("WineReviewMT")

# Get the specific tenant's version of the collection
collection_tenant_a = mt_collection.with_tenant("tenantA")

# Query tenantA's version
response = collection_tenant_a.query.fetch_objects(
    return_properties=["review_body", "title"],
    limit=1,
)

print(response.objects[0].properties)

Python Client v3

results = (
    client.query.get("MultiTenancyClass", ["property1", "property2"]).with_limit(1)
    .with_tenant("tenantA")
    .do()
)

JS/TS Client v3

const myMTCollection = client.collections.get('WineReviewMT');
const collectionTenantA = myMTCollection.withTenant('tenantA');

const multiTenantResult = await collectionTenantA.query.fetchObjects({
  limit: 1,
  returnProperties: ['review_body','title']
})

console.log(JSON.stringify(multiTenantResult.objects[0].properties, null, 2));

JS/TS Client v2

result = await client
   .graphql
   .get()
   .withClassName('MultiTenancyClass')
   .withFields('property1 property2')
   .withTenant('TenantA')
   .do();

console.log(JSON.stringify(result, null, 2));

Go

response, err := client.GraphQL().Get().
  WithClassName("MultiTenancyClass").
  WithFields(graphql.Field{Name: "property1"}, graphql.Field{Name: "property2"}).
  WithLimit(1).
  WithTenant("tenantA").
  Do(ctx)

Java

Result<List<WeaviateObject>> resultObj = client.data().objectsGetter()
  .withClassName(className)
  .withTenant(tenantName)
  .withVector()
  .run();

Replication

For collections with replication enabled, you can specify the consistency level in your queries. This applies to CRUD queries as well as searches.

Python Client v4

from weaviate.classes.config import ConsistencyLevel

questions = client.collections.get(collection_name).with_consistency_level(
    consistency_level=ConsistencyLevel.QUORUM
)
response = collection.query.fetch_object_by_id("36ddd591-2dee-4e7e-a3cc-eb86d30a4303")

# The parameter passed to `withConsistencyLevel` can be one of:
# * 'ALL',
# * 'QUORUM' (default), or
# * 'ONE'.
#
# It determines how many replicas must acknowledge a request
# before it is considered successful.

for o in response.objects:
    print(o.properties)  # Inspect returned objects

Python Client v3

import weaviate
from weaviate.data.replication import ConsistencyLevel

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

data_object = (
  client.data_object.get_by_id(
    uuid="36ddd591-2dee-4e7e-a3cc-eb86d30a4303",
    class_name="MyClass",
    consistency_level=ConsistencyLevel.ONE,
  )
)

# The parameter "consistency_level" can be one of ConsistencyLevel.ALL,
# ConsistencyLevel.QUORUM (default), or ConsistencyLevel.ONE. Determines how many
# replicas must acknowledge a request before it is considered successful.

print(data_object)

JS/TS Client v3

const myCollection = client.collections.get('Article').withConsistency('QUORUM');

const result = await myCollection.query.fetchObjectById("36ddd591-2dee-4e7e-a3cc-eb86d30a4303")

console.log(JSON.stringify(result, null, 2));

// The parameter passed to `withConsistencyLevel` can be one of:
// * 'ALL',
// * 'QUORUM' (default), or
// * 'ONE'.
//
// It determines how many replicas must acknowledge a request
// before it is considered successful.

JS/TS Client v2

import weaviate from 'weaviate-ts-client';

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

const response = await client.data
  .getterById()
  .withClassName('MyClass')
  .withId('36ddd591-2dee-4e7e-a3cc-eb86d30a4303')
  .withConsistencyLevel('ONE')  // default QUORUM
  .do();
console.log(JSON.stringify(response, null, 2));

// The parameter passed to `withConsistencyLevel` can be one of:
// * 'ALL',
// * 'QUORUM' (default), or
// * 'ONE'.
//
// It determines how many replicas must acknowledge a request
// before it is considered successful.

Go

package main

import (
    "context"
    "fmt"

    "github.com/weaviate/weaviate-go-client/v4/weaviate/data/replication"  // for consistency levels
    "github.com/weaviate/weaviate-go-client/v4/weaviate"
)

func main() {
    cfg := weaviate.Config{
        Host:   "localhost:8080",
        Scheme: "http",
    }
    client, err := weaviate.NewClient(cfg)
    if err != nil {
        panic(err)
    }

    data, err := client.Data().ObjectsGetter().
        WithClassName("MyClass").
        WithID("36ddd591-2dee-4e7e-a3cc-eb86d30a4303").
        WithConsistencyLevel(replication.ConsistencyLevel.ONE).  // default QUORUM
        Do(context.Background())

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

// The parameter passed to "WithConsistencyLevel" can be one of:
// * replication.ConsistencyLevel.ALL,
// * replication.ConsistencyLevel.QUORUM (default), or
// * replication.ConsistencyLevel.ONE.
//
// It determines how many replicas must acknowledge a request
// before it is considered successful.

Java

package io.weaviate;

import java.util.List;
import io.weaviate.client.Config;
import io.weaviate.client.WeaviateClient;
import io.weaviate.client.base.Result;
import io.weaviate.client.v1.data.model.WeaviateObject;
import io.weaviate.client.v1.data.replication.model.ConsistencyLevel;

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

    Result<List<WeaviateObject>> result = client.data().objectsGetter()
      .withClassName("MyClass")
      .withID("36ddd591-2dee-4e7e-a3cc-eb86d30a4303")
      .withConsistencyLevel(ConsistencyLevel.ONE)  // default QUORUM
      .run();

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

// The parameter passed to `withConsistencyLevel` can be one of:
// * ConsistencyLevel.ALL,
// * ConsistencyLevel.QUORUM (default), or
// * ConsistencyLevel.ONE.
//
// It determines how many replicas must acknowledge a request
// before it is considered successful.

Curl

curl "http://localhost:8080/v1/objects/MyClass/36ddd591-2dee-4e7e-a3cc-eb86d30a4303?consistency_level=QUORUM"

# The parameter "consistency_level" can be one of ALL, QUORUM (default), or ONE. Determines how many
# replicas must acknowledge a request before it is considered successful.
# curl "/v1/objects/{ClassName}/{id}?consistency_level=ONE"

Related pages

• Connect to Weaviate
• API References: GraphQL: Get
• For tutorials, see Queries
• For search using the GraphQL API, see GraphQL API

Questions and feedback

If you have any questions or feedback, let us know in the user forum.

• Technical questions
• Documentation feedback