Skip to main content

GraphQL - Get{}

LICENSEย Weaviate on Stackoverflow badgeย Weaviate issues on GitHub badgeย Weaviate version badgeย Weaviate total Docker pulls badgeย Go Report Card

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={
"X-OpenAI-Api-Key": "YOUR-OPENAI-API-KEY", # Only needed for `nearText` or `hybrid` queries
},
)

Get{} syntax and query structureโ€‹

The Get{} function fetches fields described in the schema. For example, if you've created a schema with a class JeopardyQuestion which has the properties question, answer and points, you can query it as follows:

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)

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
]
}
}
}
Get query without arguments

The order of object retrieval is not guaranteed in a Get query without any search parameters or filters. Accordingly, such a Get query is not suitable for any substantive object retrieval strategy. Consider the Cursor API for that purpose.

groupBy argumentโ€‹

You can use a groupBy argument to retrieve groups of objects from Weaviate. This functionality offers the advantage of maintaining granular search results by searching through detailed or segmented objects (e.g. chunks of documents), while also enabling you to step back and view the broader context of the objects (e.g. documents as a whole).

The groupBy{} argument is structured as follows for the Get{} function:

Single-level grouping only

As of 1.19, the groupBy path is limited to one property or cross-reference. Nested paths are current not supported.

{
Get{
<Class>(
<vectorSearchParameter> # 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
}
}
}
}
}
}
}

Take a collection of Passage objects for example, each object belonging to a Document. If searching through Passage objects, you can group the results according to any property of the Passage, including the cross-reference property that represents the Document each Passage is associated with.

The groups and objectsPerGroup limits are customizable. So in this example, you could retrieve the top 1000 objects and group them to identify the 3 most relevant Document objects, based on the top 3 Passage objects from each Document.

More concretely, a query such as below:

Example Get query with groupBy
{
Get{
Passage(
limit: 100
nearObject: {
id: "00000000-0000-0000-0000-000000000001"
}
groupBy: {
path: ["content"]
groups: 2
objectsPerGroup: 2
}
){
_additional {
id
group {
id
count
groupedBy { value path }
maxDistance
minDistance
hits{
content
ofDocument {
... on Document {
_additional {
id
}
}
}
_additional {
id
distance
}
}
}
}
}
}
}

Will result in the following response:

Corresponding response
{
"data": {
"Get": {
"Passage": [
{
"_additional": {
"group": {
"count": 1,
"groupedBy": {
"path": [
"content"
],
"value": "Content of passage 1"
},
"hits": [
{
"_additional": {
"distance": 0,
"id": "00000000-0000-0000-0000-000000000001"
},
"content": "Content of passage 1",
"ofDocument": [
{
"_additional": {
"id": "00000000-0000-0000-0000-000000000011"
}
}
]
}
],
"id": 0,
"maxDistance": 0,
"minDistance": 0
},
"id": "00000000-0000-0000-0000-000000000001"
}
},
{
"_additional": {
"group": {
"count": 1,
"groupedBy": {
"path": [
"content"
],
"value": "Content of passage 2"
},
"hits": [
{
"_additional": {
"distance": 0.00078231096,
"id": "00000000-0000-0000-0000-000000000002"
},
"content": "Content of passage 2",
"ofDocument": [
{
"_additional": {
"id": "00000000-0000-0000-0000-000000000011"
}
}
]
}
],
"id": 1,
"maxDistance": 0.00078231096,
"minDistance": 0.00078231096
},
"id": "00000000-0000-0000-0000-000000000002"
}
}
]
}
}
}

Consistency levelsโ€‹

Available from v1.19 onwards

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.

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}")

Query beacon referencesโ€‹

If you've set a beacon reference (cross-reference) in the schema, you can query it as follows:

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โ€‹

For every Get{} request you can get additional information about the returned data object(s) by using additional properties. You can recognize these properties because they are in the object _additional{}. Additional properties can help you interpret query results and can for example be used for projection and visualization of the retrieved data. An overview of all additional properties and how to use them is documented here.

Vector Search Operatorsโ€‹

To combine Get { } with a vector search argument, here is an overview of the supported arguments and links to their detailed documentation:

ArgumentDescriptionRequired modules (at least one of)Learn more
nearObjectFind the nearest neighbors of an object referenced by its idnone - works out of the boxLearn more
nearVectorFind the nearest neighbors to any vectornone - works out of the boxLearn more
nearTextVectorize a text query and perform a vector search based on ittext2vec-transformers, text2vec-contextionary, text2vec-openai, multi2vec-clip, text2vec-huggingface, text2vec-cohereTransformers, Contextionary, OpenAI, CLIP, Hugging Face, Cohere
nearImageVectorize an image and perform a vector search based on itmulti2vec-clip, img2vec-neuralCLIP, Img2Vec
hybridCombine dense and sparse vectors to deliver best of both search methodsnone - works out of the boxLearn more
bm25Keyword search with BM25F rankingnone - works out of the boxLearn more

Filtersโ€‹

Get{} functions can be extended with search filters (both semantic filters and traditional filters). Because the filters work on multiple core functions (like Aggregate{}) there is a specific documentation page dedicated to filters.

Sortingโ€‹

Note: Support for sorting was added in v1.13.0.

You can sort results by any primitive property, typically a text, string, number, or int property. When a query has a natural order (e.g. because of a near<Media> vector search), adding a sort operator will override the order.

See filters โ€“ sorting for more information.

More Resourcesโ€‹

If you can't find the answer to your question here, please look at the:

  1. Frequently Asked Questions. Or,
  2. Knowledge base of old issues. Or,
  3. For questions: Stackoverflow. Or,
  4. For more involved discussion: Weaviate Community Forum. Or,
  5. We also have a Slack channel.