Skip to main content

Object-level queries (Get)

Overview

This page covers object-level query functions. They are collectively referred to as Get queries within.

Parameters

A Get query requires the target collection to be specified.

  • In GraphQL calls, the properties to be retrieved to be must be specified explicitly.

  • In gRPC calls, all properties are fetched by default.

  • Metadata retrieval is optional in both GraphQL and gRPC calls.

Available arguments

Each Get query can include any of the following types of arguments:

ArgumentDescriptionRequired
CollectionAlso called "class". The object collection to be retrieved from.Yes
PropertiesProperties to be retrievedYes (GraphQL)
(No if using gRPC API)
Cross-referencesCross-references to be retrievedNo
MetadataMetadata (additional properties) to be retrievedNo
Conditional filtersFilter the objects to be retrievedNo
Search operatorsSpecify the search strategy (e.g. near text, hybrid, bm25)No
Additional operatorsSpecify additional operators (e.g. limit, offset, sort)No
Tenant nameSpecify the tenant nameYes, if multi-tenancy enabled. (Read more: what is multi-tenancy?)
Consistency levelSpecify the consistency levelNo

Example usage

import weaviate
import weaviate.classes as wvc
import os

client = weaviate.connect_to_local()

try:
collection = client.collections.get("JeopardyQuestion")
response = collection.query.fetch_objects()

for o in response.objects:
print(o.properties) # Inspect returned objects
finally:
client.close()
Example response

The above query will result in something like the following:


Order of retrieved objects

Without any arguments, the objects are retrieved according to their ID.

Accordingly, such a Get query is not suitable for a substantive object retrieval strategy. Consider the Cursor API for that purpose.

Get groupBy

You can use retrieve groups of objects that match the query.

The groups are defined by a property, and the number of groups and objects per group can be limited.

groupBy limitations
  • groupBy only works with near<Media> operators.
  • The groupBy path is limited to one property or cross-reference. Nested paths are not supported.

Syntax

{
Get{
<Class>(
<vectorSearchOperator> # e.g. nearVector, nearObject, nearText
groupBy:{
path: [<propertyName>] # Property to group by (only one property or cross-reference)
groups: <number> # Max. number of groups
objectsPerGroup: <number> # Max. number of objects per group
}
) {
_additional {
group {
id # An identifier for the group in this search
groupedBy{ value path } # Value and path of the property grouped by
count # Count of objects in this group
maxDistance # Maximum distance from the group to the query vector
minDistance # Minimum distance from the group to the query vector
hits { # Where the actual properties for each grouped objects will be
<properties> # Properties of the individual object
_additional {
id # UUID of the individual object
vector # The vector of the individual object
distance # The distance from the individual object to the query vector
}
}
}
}
}
}
}

Example usage:

    questions = client.collections.get("JeopardyQuestion")
response = questions.query.near_text(
query="animals",
distance=0.2,
group_by=wvc.query.GroupBy(
prop="points",
number_of_groups=3,
objects_per_group=5
)
)

for k, v in response.groups.items(): # View by group
print(k, v)

for o in response.objects: # View by object
print(o)

Consistency levels

Added in v1.19

Where replication is enabled, you can specify a consistency argument with a Get query. The available options are:

  • ONE
  • QUORUM (Default)
  • ALL

Read more about consistency levels here.

import weaviate
import weaviate.classes as wvc
import os

client = weaviate.connect_to_local()

try:
questions = client.collections.get("JeopardyQuestion").with_consistency_level(consistency_level=wvc.config.ConsistencyLevel.QUORUM)
response = collection.query.fetch_objects()

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

Multi-tenancy

Added in v1.20

In a multi-tenancy collection, each Get query must specify a tenant.

multi_collection = client.collections.get("MultiTenancyCollection")

# Get collection specific to the required tenant
multi_tenantA = multi_collection.with_tenant("tenantA")

# Query tenantA
result = multi_tenantA.query.fetch_objects(
limit=2,
)

print(result.objects[0].properties)

Cross-references

Weaviate supports cross-references between objects. Each cross-reference behaves like a property.

You can retrieve cross-referenced properties with a Get query.

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

for o in response.objects:
print(f"References for {o.uuid}")
for ro in o.references["hasCategory"].objects: # Inspect returned references
print(ro.properties)
Expected response
{
"data": {
"Get": {
"JeopardyQuestion": [
{
"answer": "Jonah",
"hasCategory": [
{
"title": "THE BIBLE"
}
],
"points": 100,
"question": "This prophet passed the time he spent inside a fish offering up prayers"
},
// shortened for brevity
]
}
}
}

Additional properties / metadata

Various metadata properties may be retrieved with Get{} requests. They include:

PropertyDescription
idObject id
vectorObject vector
generateGenerative module outputs
rerankReranker module outputs
creationTimeUnixObject creation time
lastUpdateTimeUnixObject last updated time
distanceVector distance to query (vector search only)
certaintyVector distance to query, normalized to certainty (vector search only)
scoreSearch score (BM25 and hybrid only)
explainScoreExplanation of the score (BM25 and hybrid only)
classificationClassification outputs
featureProjectionFeature projection outputs

They are returned through the _additional properties in the response.

For further information see:

Search operators

The following search operators are available.

ArgumentDescriptionRequired integration typeLearn more
nearObjectVector search using a Weaviate objectnoneLearn more
nearVectorVector search using a raw vectornoneLearn more
nearTextVector search using a text queryText embedding model
nearImageVector search using an imageMulti-modal embedding model
hybridCombine vector and BM25 search resultsnoneLearn more
bm25Keyword search with BM25F rankingnoneLearn more

For further information see:

Conditional filters

Get{} queries can be combined with a conditional filter.

For further information see:

Additional operators

Get{} queries can be combined with additional operators such as limit, offset, autocut, after or sort.

For further information see:

Questions and feedback

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