Skip to main content

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.

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

for o in response.objects:
    print(o.properties)
py docs  API docs
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.

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

for o in response.objects:
    print(o.properties)
py docs  API docs
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.

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

for o in response.objects:
    print(o.properties)
py docs  API docs
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.

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)
py docs  API docs
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.)

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

print(response.objects[0].vector["default"])
py docs  API docs
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).

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)
py docs  API docs
Example response

The output is like this:

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

Retrieve cross-referenced properties​

Cross-references and query performance

Queries involving cross-references can be slower than queries that do not involve cross-references, especially at scale such as for multiple objects or complex queries.

At the first instance, we strongly encourage you to consider whether you can avoid using cross-references in your data schema. As a scalable AI-native database, Weaviate is well-placed to perform complex queries with vector, keyword and hybrid searches involving filters. You may benefit from rethinking your data schema to avoid cross-references where possible.

For example, instead of creating separate "Author" and "Book" collections with cross-references, consider embedding author information directly in Book objects and using searches and filters to find books by author characteristics.

To retrieve properties from cross-referenced objects, specify:

  • The cross-reference property
  • The target cross-referenced collection
  • The properties to retrieve
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)
py docs  API docs
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.

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
py docs  API docs

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.

# 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)
py docs  API docs

Replication​

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

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
py docs  API docs

Questions and feedback​

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