Basic search examples

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.

Basic search

You can get objects without specifying any parameters. This returns objects ordered by their UUID.

Python (v4)

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

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

Python (v3)

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

print(response)

JS/TS (Beta)

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

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

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

JS/TS

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

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

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 (v4)

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

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

Python (v3)

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

print(response)

JS/TS (Beta)

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

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

JS/TS

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

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

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 (v4)

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

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

Python (v3)

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

print(response)

JS/TS (Beta)

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

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

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

JS/TS

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

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

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 (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 (v3)

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

print(response)

JS/TS (Beta)

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

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

  limit: 1,
  offset: 1,
})

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

JS/TS

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

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

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 (v4)

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

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

Python (v3)

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

print(response)

JS/TS (Beta)

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

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

})

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

JS/TS

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

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

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 (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 (v3)

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

print(response)

JS/TS (Beta)

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

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

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

JS/TS

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

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

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 (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 (v3)

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

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

TS/JS (Beta)

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

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

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

TS/JS

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

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

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 (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 (v3)

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

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

JS/TS (Beta)

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

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

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

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 (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 (v3)

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

TS/JS (Beta)

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

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

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

TS/JS

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

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

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 (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 (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 (Beta)

const collectionName = 'Article';
const myCollection = client.collections.get(collectionName).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

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, please let us know on our forum. For example, you can:

• Provide feedback on the documentation
• Ask a technical question