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

jeopardy = client.collections.use("JeopardyQuestion")response = jeopardy.query.fetch_objects()for o in response.objects:    print(o.properties)

JavaScript/TypeScript

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

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

Java

CollectionHandle<Map<String, Object>> jeopardy =    client.collections.use("JeopardyQuestion");var response = jeopardy.query.fetchObjects();for (var o : response.objects()) {  System.out.println(o.properties());}

var jeopardy = client.Collections.Use("JeopardyQuestion");var response = await jeopardy.Query.FetchObjects();foreach (var o in response.Objects){    Console.WriteLine(JsonSerializer.Serialize(o.Properties));}

GraphQL

{
  Get {
    JeopardyQuestion {
      question
    }
  }
}

Example response

The output is like this:

JSON

{
  "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

jeopardy = client.collections.use("JeopardyQuestion")response = jeopardy.query.fetch_objects(    limit=1)for o in response.objects:    print(o.properties)

JavaScript/TypeScript

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

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

Java

CollectionHandle<Map<String, Object>> jeopardy =    client.collections.use("JeopardyQuestion");var response = jeopardy.query.fetchObjects(    q -> q.limit(1));for (var o : response.objects()) {  System.out.println(o.properties());}

var jeopardy = client.Collections.Use("JeopardyQuestion");var response = await jeopardy.Query.FetchObjects(    limit: 1);foreach (var o in response.Objects){    Console.WriteLine(JsonSerializer.Serialize(o.Properties));}

GraphQL

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

Example response

The output is like this:

JSON

{
  "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

jeopardy = client.collections.use("JeopardyQuestion")response = jeopardy.query.fetch_objects(    limit=1,    offset=1)for o in response.objects:    print(o.properties)

JavaScript/TypeScript

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

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

Java

CollectionHandle<Map<String, Object>> jeopardy =    client.collections.use("JeopardyQuestion");var response = jeopardy.query.fetchObjects(    q -> q.limit(1).offset(1));for (var o : response.objects()) {  System.out.println(o.properties());}

var jeopardy = client.Collections.Use("JeopardyQuestion");var response = await jeopardy.Query.FetchObjects(offset: 1, limit: 1);foreach (var o in response.Objects){    Console.WriteLine(JsonSerializer.Serialize(o.Properties));}

GraphQL

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

Example response

The output is like this:

JSON

{
  "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.

Retrieve object `properties`

You can specify which object properties to return. By default, all properties and object UUIDs are returned. Blob and reference properties are excluded unless specified otherwise (this does not apply to the Go client library).

Python

jeopardy = client.collections.use("JeopardyQuestion")response = jeopardy.query.fetch_objects(    limit=1,    return_properties=["question", "answer", "points"])for o in response.objects:    print(o.properties)

JavaScript/TypeScript

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

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

CollectionHandle<Map<String, Object>> jeopardy =    client.collections.use("JeopardyQuestion");var response = jeopardy.query.fetchObjects(    q -> q.limit(1).returnProperties("question", "answer", "points"));for (var o : response.objects()) {  System.out.println(o.properties());}

var jeopardy = client.Collections.Use("JeopardyQuestion");var response = await jeopardy.Query.FetchObjects(    limit: 1,    returnProperties: new[] { "question", "answer", "points" });foreach (var o in response.Objects){    Console.WriteLine(JsonSerializer.Serialize(o.Properties));}

GraphQL

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

Example response

The output is like this:

JSON

{
  "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

jeopardy = client.collections.use("JeopardyQuestion")response = jeopardy.query.fetch_objects(    include_vector=True,    limit=1)print(response.objects[0].vector["default"])

JavaScript/TypeScript

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

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

Java

CollectionHandle<Map<String, Object>> jeopardy =    client.collections.use("JeopardyQuestion");var response = jeopardy.query.fetchObjects(q -> q    .includeVector()    .limit(1));if (!response.objects().isEmpty()) {  System.out.println(response.objects().get(0).vectors());}

var jeopardy = client.Collections.Use("JeopardyQuestion");var response = await jeopardy.Query.FetchObjects(    includeVectors: new[] { "default" },    limit: 1);Console.WriteLine("Vector for 'default':");if (response.Objects.Any()){    Console.WriteLine(JsonSerializer.Serialize(response.Objects.First()));}

GraphQL

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

Example response

The output is like this:

JSON

{
  "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

jeopardy = client.collections.use("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)

JavaScript/TypeScript

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

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

Java

CollectionHandle<Map<String, Object>> jeopardy =
    client.collections.use("JeopardyQuestion");
var response = jeopardy.query.fetchObjects(
    // Object IDs are included by default with the v6 client! :)
    q -> q.limit(1));

for (var o : response.objects()) {
  System.out.println(o.uuid());
}

var jeopardy = client.Collections.Use("JeopardyQuestion");
// Ensure you use a UUID that actually exists in your DB, or fetch one first
var allObjs = await jeopardy.Query.FetchObjects(limit: 1);
var idToFetch = allObjs.Objects.First().UUID;

var response = await jeopardy.Query.FetchObjectByID((Guid)idToFetch);

Console.WriteLine(response);

GraphQL

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

Example response

The output is like this:

JSON

{
  "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

from weaviate.classes.query import QueryReferencejeopardy = client.collections.use("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)

JavaScript/TypeScript

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

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)

Java

CollectionHandle<Map<String, Object>> jeopardy =    client.collections.use("JeopardyQuestion");var response = jeopardy.query.fetchObjects(q -> q    .returnReferences(QueryReference.single("hasCategory",        r -> r.returnProperties("title")))    .limit(2));for (var o : response.objects()) {  System.out.println(o.properties().get("question"));  // print referenced objects  if (o.references() != null && o.references().get("hasCategory") != null) {    for (var refObj : o.references().get("hasCategory")) {      System.out.println(refObj);    }  }}

var jeopardy = client.Collections.Use("JeopardyQuestion");var response = await jeopardy.Query.FetchObjects(    returnReferences: [new QueryReference(linkOn: "hasCategory", fields: ["title"])],    limit: 2);foreach (var o in response.Objects){    if (o.Properties.ContainsKey("question"))        Console.WriteLine(o.Properties["question"]);    // print referenced objects    // Note: References are grouped by property name ('hasCategory')    if (o.References != null && o.References.ContainsKey("hasCategory"))    {        foreach (var refObj in o.References["hasCategory"])        {            Console.WriteLine(JsonSerializer.Serialize(refObj.Properties));        }    }}

GraphQL

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

Example response

The output is like this:

JSON

{
    "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

from weaviate.classes.query import MetadataQueryjeopardy = client.collections.use("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

JavaScript/TypeScript

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

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

CollectionHandle<Map<String, Object>> jeopardy =    client.collections.use("JeopardyQuestion");var response = jeopardy.query.fetchObjects(q -> q.limit(1)    .returnMetadata(Metadata.CREATION_TIME_UNIX));for (var o : response.objects()) {  System.out.println(o.properties()); // View the returned properties  System.out.println(o.createdAt()); // View the returned creation time}

var jeopardy = client.Collections.Use("JeopardyQuestion");var response = await jeopardy.Query.FetchObjects(    limit: 1,    returnMetadata: MetadataOptions.CreationTime);foreach (var o in response.Objects){    Console.WriteLine(JsonSerializer.Serialize(o.Properties)); // View the returned properties    Console.WriteLine(o.Metadata.CreationTime); // View the returned creation time}

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

# Connect to the collectionmt_collection = client.collections.use("WineReviewMT")# Get the specific tenant's version of the collectioncollection_tenant_a = mt_collection.with_tenant("tenantA")# Query tenantA's versionresponse = collection_tenant_a.query.fetch_objects(    return_properties=["review_body", "title"],    limit=1,)print(response.objects[0].properties)

JavaScript/TypeScript

const myMTCollection = client.collections.use('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));

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

Java

// Connect to the collectionCollectionHandle<Map<String, Object>> mtCollection =    client.collections.use("WineReviewMT");// Get the specific tenant's version of the collectionvar collectionTenantA = mtCollection.withTenant("tenantA");// Query tenantA's versionvar response = collectionTenantA.query    .fetchObjects(q -> q.returnProperties("review_body", "title").limit(1));if (!response.objects().isEmpty()) {  System.out.println(response.objects().get(0).properties());}

var mtCollection = client.Collections.Use("WineReviewMT").WithTenant("tenantA");

var response = await mtCollection.Query.FetchObjects(
    returnProperties: new[] { "review_body", "title" },
    limit: 1
);

if (response.Objects.Any())
{
    Console.WriteLine(JsonSerializer.Serialize(response.Objects.First().Properties));
    Assert.Equal("WineReviewMT", response.Objects.First().Collection);
}

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

from weaviate.classes.config import ConsistencyLevel

JavaScript/TypeScript

const myCollection = client.collections.use('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.

package main

import (
    "context"
    "fmt"

    "github.com/weaviate/weaviate-go-client/v5/weaviate/data/replication"  // for consistency levels
    "github.com/weaviate/weaviate-go-client/v5/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

var jeopardyWithConsistency = client.collections.use("JeopardyQuestion")    .withConsistencyLevel(ConsistencyLevel.QUORUM);var response = jeopardyWithConsistency.query.fetchObjectById(uuid);System.out.println(response.get().properties());

var jeopardy = client
    .Collections.Use("JeopardyQuestion")
    .WithConsistencyLevel(ConsistencyLevels.Quorum);

var response = await jeopardy.Query.FetchObjectByID((Guid)validId);

// 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.

Console.WriteLine(response);

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"

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

Questions and feedback

Have a question or feedback? Here's how to reach us.

Community Forum

Ask questions and connect with other developers on our Community forum.

Support

Weaviate Cloud user or customer? Find the right channel on the Support page.

List objects

limit returned objects

Paginate with limit and offset

Retrieve object properties

Retrieve the object vector

Retrieve the object id

Retrieve cross-referenced properties

Retrieve metadata values

Multi-tenancy

Replication

Related pages

Questions and feedback

`limit` returned objects

Paginate with `limit` and `offset`

Retrieve object `properties`

Retrieve the object `vector`

Retrieve the object `id`