Skip to main content

GraphQL - Get{}

TIP: Try these queries

You can try these queries on our demo instance (https://edu-demo.weaviate.network). You can authenticate against it with the read-only Weaviate API key learn-weaviate, and run the query with your preferred Weaviate client.


We include client instantiation examples below:

edu-demo client instantiation
import weaviate

# Instantiate the client with the auth config
client = weaviate.Client(
url='https://edu-demo.weaviate.network',
auth_client_secret=weaviate.AuthApiKey(api_key='learn-weaviate'),
additional_headers={
# Only needed if using an inference service (e.g. `nearText`, `hybrid` or `generative` queries)
'X-OpenAI-Api-Key': 'YOUR-OPENAI-API-KEY',
},
)

Overview

The Get{} function is for retrieving individual objects.

Syntax and query structure

The Get{} function requires the target class name, and the properties to be fetched.

For example, the following will fetch JeopardyQuestion objects and their question, answer and points properties:

import weaviate

client = weaviate.Client(
"https://some-endpoint.weaviate.network", # Replace with your Weaviate URL
)

result = client.query.get("JeopardyQuestion", ["question", "answer", "points"]).do()
print(result)
Example response

The above query will result in something like the following:

{
"data": {
"Get": {
"JeopardyQuestion": [
{
"answer": "Jonah",
"points": 100,
"question": "This prophet passed the time he spent inside a fish offering up prayers"
},
// shortened for brevity
]
}
}
}
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.

groupBy argument

You can use groupBy to retrieve groups of objects from Weaviate. The groupBy{} argument is structured as follows for the Get{} function:

Current limitations
  • groupBy can only be used with near<Media> operators. It is not possible to use it with bm25 or hybrid queries.
  • The groupBy path is limited to one property or cross-reference. Nested paths are current not supported.
{
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
}
}
}
}
}
}
}

Consistency levels

Added in v1.19

Where replication is configured, the Get{} function can be configured to return results with different levels of consistency. This is useful when you want to retrieve the most up-to-date data, or when you want to retrieve data as fast as possible.

The available consistency options are:

  • ONE
  • QUORUM
  • ALL

Read more about consistency levels here.

import weaviate
from weaviate.data.replication import ConsistencyLevel

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

resp = (
client.query.get("Article", ["name"])
.with_additional("isConsistent")
.with_consistency_level(ConsistencyLevel.ONE)
.do()
)

print(f"resp: {resp}")

Multi-tenancy

Added in v1.20

Where multi-tenancy is configured, the Get{} function can be configured to return results from a specific tenant.

You can do so by specifying the tenant parameter in the GraphQL query as shown below, or using the equivalent client function.

{
Get {
Article (
tenant: "tenantA"
limit: 1
) {
name
}
}
}

Cross-references

You can retrieve any cross-referenced properties.

import weaviate

client = weaviate.Client(
"https://some-endpoint.weaviate.network", # Replace with your Weaviate URL
)

result = client.query.get("JeopardyQuestion", ["question", "answer", "points", "hasCategory {... on JeopardyCategory {title }}"]).do()

print(result)
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 modules (at least one of)Learn more
nearObjectVector search using a Weaviate objectnoneLearn more
nearVectorVector search using a raw vectornoneLearn more
nearTextVector search using a text querytext2vec-xxxTransformers, Contextionary, OpenAI, CLIP, Hugging Face, Cohere
nearImageVector search using an imagemulti2vec-clip, img2vec-neuralCLIP, Img2Vec
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: