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: | Argument | Description | Required | | ------------------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | Collection | Also called "class". The object collection to be retrieved from. | Yes | | Properties | Properties to be retrieved | Yes (GraphQL)
(No if using gRPC API) | | Cross-references | Cross-references to be retrieved | No | | [Metadata](graphql-additional-properties.md) | Metadata (additional properties) to be retrieved | No | | [Conditional filters](graphql-filters.md) | Filter the objects to be retrieved | No | | [Search operators](graphql-search-operators.md) | Specify the search strategy (e.g. near text, hybrid, bm25) | No | | [Additional operators](graphql-additional-operators.md) | Specify additional operators (e.g. limit, offset, sort) | No | | [Tenant name](#multi-tenancy) | Specify the tenant name | Yes, if multi-tenancy enabled. ([Read more: what is multi-tenancy?](../concepts/data.md#multi-tenancy)) | | [Consistency level](#consistency-levels) | Specify the consistency level | No | #### Example usage :::code-group{sync="languages"} ```python title="Python" import weaviate import weaviate.classes as wvc import os client = weaviate.connect_to_local() ``` ```go title="Go" package main import ( "context" "fmt" "github.com/weaviate/weaviate-go-client/v5/weaviate" "github.com/weaviate/weaviate-go-client/v5/weaviate/graphql" ) func main() { cfg := weaviate.Config{ Host: "WEAVIATE_INSTANCE_URL", // Replace with your Weaviate URL Scheme: "https", } client, err := weaviate.NewClient(cfg) if err != nil { panic(err) } fields := []graphql.Field{ {Name: "question"}, {Name: "answer"}, {Name: "points"}, } ctx := context.Background() result, err := client.GraphQL().Get(). WithClassName("JeopardyQuestion"). WithFields(fields...). Do(ctx) if err != nil { panic(err) } fmt.Printf("%v", result) } ``` ```bash title="Curl" echo '{ "query": "{ Get { JeopardyQuestion { question answer points } } }" }' | curl \ -X POST \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer learn-weaviate' \ -d @- \ https://edu-demo.weaviate.network/v1/graphql ``` ```graphql title="GraphQL" { Get { JeopardyQuestion { question answer points } } } ``` ::: :::accordion{title="Example response"} The above query will result in something like the following: ``` {'points': 400.0, 'answer': 'Refrigerator Car', 'air_date': '1997-02-14', 'hasCategory': 'TRANSPORTATION', 'question': 'In the 19th century Gustavus Swift developed this type of railway car to preserve his packed meat', 'round': 'Jeopardy!'} {'points': 800.0, 'hasCategory': 'FICTIONAL CHARACTERS', 'answer': 'Forsyte', 'air_date': '1998-05-27', 'question': 'Last name of Soames & Irene, the 2 principal characters in John Galsworthy\'s 3 novel "saga"', 'round': 'Double Jeopardy!'} {'points': 500.0, 'answer': 'Duluth', 'air_date': '1996-12-17', 'hasCategory': 'MUSEUMS', 'question': 'This eastern Minnesota city is home to the Lake Superior Museum of Transportation', 'round': 'Jeopardy!'} {'points': 1000.0, 'answer': 'Ear', 'air_date': '1988-11-16', 'hasCategory': 'HISTORY', 'round': 'Double Jeopardy!', 'question': "An eighteenth-century war was named for this part of Robert Jenkins' body, reputedly cut off by Spaniards"} {'points': 400.0, 'answer': 'Bonnie Blair', 'air_date': '1997-02-28', 'hasCategory': 'SPORTS', 'round': 'Jeopardy!', 'question': "At the 1994 Olympics, this U.S. woman speed skater surpassed Eric Heiden's medal total"} {'points': 1600.0, 'answer': 'Turkish', 'air_date': '2008-03-24', 'hasCategory': 'LANGUAGES', 'question': 'In the 1920s this language of Anatolia switched from the Arabic to the Latin alphabet', 'round': 'Double Jeopardy!'} {'points': 100.0, 'answer': 'Ireland', 'air_date': '1998-10-01', 'hasCategory': 'POTPOURRI', 'round': 'Jeopardy!', 'question': "Country in which you'd find the Book of Kells"} {'points': 800.0, 'answer': 'Ichabod Crane', 'air_date': '2008-01-03', 'hasCategory': 'LITERATURE', 'round': 'Double Jeopardy!', 'question': 'Washington Irving based this character on his friend Jesse Merwin, a schoolteacher'} {'points': 300.0, 'air_date': '1997-12-05', 'hasCategory': 'LITERATURE', 'answer': '"The Prince and the Pauper"', 'question': 'Tom Canty, born in a slum called Offal Court, & Edward Tudor are the title characters in this Twain novel', 'round': 'Jeopardy!'} {'points': 500.0, 'answer': 'Seattle', 'air_date': '1999-05-10', 'hasCategory': 'U.S. CITIES', 'round': 'Jeopardy!', 'question': "The site of the World's Fair in 1962, it's flanked on the west by Puget Sound & on the east by Lake Washington"} ``` ::: :::accordion{title="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](graphql-additional-operators.md#cursor-with-after) for that purpose. ::: :::callout{intent="tip" title="Read more"} - [How-to search: Basics](../how-to-query-search/basics.md) ::: ### `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. :::callout{intent="note" title="`groupBy` limitations"} - `groupBy` only works with `near` operators. - The `groupBy` `path` is limited to one property or cross-reference. Nested paths are not supported. ::: #### Syntax ```graphql { Get{ ( # e.g. nearVector, nearObject, nearText groupBy:{ path: [] # Property to group by (only one property or cross-reference) groups: # Max. number of groups objectsPerGroup: # 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 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: ::::tabs{sync="languages"} :::tab{title="Python"} ```python questions = client.collections.use("JeopardyQuestion") response = questions.query.near_text( query="animals", 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) ``` ::: :::: :::tab{title="Raw GraphQL"} The other clients do not yet natively support groupby operations. Please use "raw" graphql queries to perform groupby operations. ```graphql { Get{ JeopardyQuestion( nearText: { concepts: ["animals"], distance: 0.2 } groupBy: { # How to group the results path: ["points"] groups: 3 objectsPerGroup: 5 } ) { _additional { group { # Data to be returned id groupedBy{ value path } count hits { # Actual properties to be retrieved question answer _additional { id distance } } } } } } } ``` ::: \::: ### Consistency levels 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](../replication-architecture/consistency.md). :::code-group{sync="languages"} ```python title="Python" import weaviate import weaviate.classes as wvc import os client = weaviate.connect_to_local() ``` ```go title="Go" resp, err := client.GraphQL().Get(). WithClassName("Article"). WithFields(fields...). WithConsistencyLevel(replication.ConsistencyLevel.QUORUM). Do(ctx) ``` ```graphql title="GraphQL" { Get { Article (consistencyLevel: QUORUM) { name _additional { isConsistent } } } } ``` ::: ### Multi-tenancy In a multi-tenancy collection, each `Get` query must specify a tenant. :::code-group{sync="languages"} ```python title="Python" {4,7-9} multi_collection = client.collections.use("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) ``` ```go title="Go" {4} result, err := client.GraphQL().Get(). WithClassName("MultiTenancyCollection"). WithFields(graphql.Field{Name: "question"}). WithTenant("tenantA"). Do(ctx) ``` ```graphql title="GraphQL" { Get { MultiTenancyCollection ( tenant: "tenantA" limit: 2 ) { name } } } ``` ::: :::callout{intent="tip" title="Read more"} - [How-to manage data: Multi-tenancy operations](../how-to-manage-collections/multi-tenancy.md) ::: ## Cross-references :::callout{intent="warning" title="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 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. ::: Weaviate supports cross-references between objects. Each cross-reference behaves like a property. You can retrieve cross-referenced properties with a `Get` query. :::code-group{sync="languages"} ```python title="Python" questions = client.collections.use("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) ``` ```go title="Go" package main import ( "context" "fmt" "github.com/weaviate/weaviate-go-client/v5/weaviate" "github.com/weaviate/weaviate-go-client/v5/weaviate/graphql" ) func main() { cfg := weaviate.Config{ Host: "localhost:8080", Scheme: "http", } client, err := weaviate.NewClient(cfg) if err != nil { panic(err) } ctx := context.Background() fields := []graphql.Field{ {Name: "title"}, {Name: "url"}, {Name: "wordCount"}, {Name: "inPublication", Fields: []graphql.Field{ {Name: "... on Publication", Fields: []graphql.Field{ {Name: "name"}, }}, }}, } result, err := client.GraphQL().Get(). WithClassName("Article"). WithFields(fields...). Do(ctx) if err != nil { panic(err) } fmt.Printf("%v", result) } ``` ```bash title="Curl" echo '{ "query": "{ Get { Article { title url wordCount inPublication { ... on Publication { name } } } } }" }' | curl \ -X POST \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer learn-weaviate' \ -d @- \ https://edu-demo.weaviate.network/v1/graphql ``` ```graphql title="GraphQL" { Get { JeopardyQuestion { question answer points hasCategory { # the reference property ... on JeopardyCategory { # the destination class title # the property related to target class } } } } } ``` ::: :::accordion{title="Expected response"} ```json { "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 ] } } } ``` ::: :::callout{intent="tip" title="Read more"} - [How-to retrieve cross-referenced properties](../how-to-query-search/basics.md#retrieve-cross-referenced-properties) ::: ## Additional properties / metadata Various metadata properties may be retrieved with `Get{}` requests. They include: | Property | Description | | -------------------- | ---------------------------------------------------------------------- | | `id` | Object id | | `vector` | Object vector | | `generate` | Generative module outputs | | `rerank` | Reranker module outputs | | `creationTimeUnix` | Object creation time | | `lastUpdateTimeUnix` | Object last updated time | | `distance` | Vector distance to query (vector search only) | | `certainty` | Vector distance to query, normalized to certainty (vector search only) | | `score` | Search score (BM25 and hybrid only) | | `explainScore` | Explanation of the score (BM25 and hybrid only) | | `classification` | Classification outputs | | `featureProjection` | Feature projection outputs | They are returned through the `_additional` properties in the response. For further information see: :::callout{intent="tip" title="Read more"} - [References: GraphQL: Additional properties](graphql-additional-properties.md) - [How-to search: Specify fetched properties](../how-to-query-search/basics.md#retrieve-object-properties) ::: ## Search operators The following search operators are available. | Argument | Description | Required integration type | Learn more | | ------------ | -------------------------------------- | --------------------------- | ----------------------------------------------------------- | | `nearObject` | Vector search using a Weaviate object | _none_ | [Learn more](graphql-search-operators.md#nearobject) | | `nearVector` | Vector search using a raw vector | _none_ | [Learn more](graphql-search-operators.md#nearvector) | | `nearText` | Vector search using a text query | Text embedding model | [Learn more](graphql-search-operators.md#neartext) | | `nearImage` | Vector search using an image | Multi-modal embedding model | [Learn more](graphql-search-operators.md#multimodal-search) | | `hybrid` | Combine vector and BM25 search results | _none_ | [Learn more](graphql-search-operators.md#hybrid) | | `bm25` | Keyword search with BM25F ranking | _none_ | [Learn more](graphql-search-operators.md#bm25) | For further information see: :::callout{intent="tip" title="Read more"} - [References: GraphQL: Search operators](graphql-search-operators.md) - [How-to search: Similarity search](../how-to-query-search/similarity.md) - [How-to search: Image search](../how-to-query-search/image.md) - [How-to search: BM25 search](../how-to-query-search/bm25.md) - [How-to search: Hybrid search](../how-to-query-search/hybrid.md) ::: ## Conditional filters `Get{}` queries can be combined with a conditional filter. For further information see: :::callout{intent="tip" title="Read more"} - [References: GraphQL: Conditional Filters](graphql-filters.md) - [How-to search: Filters](../how-to-query-search/filters.md) ::: ## Additional operators `Get{}` queries can be combined with additional operators such as `limit`, `offset`, `autocut`, `after` or `sort`. For further information see: :::callout{intent="tip" title="Read more"} - [References: GraphQL: Additional Operators](graphql-additional-operators.md) ::: ## Related pages - [How-to: Search: Basics](../how-to-query-search/basics.md) ## Questions and feedback Have a question or feedback? Here's how to reach us. ::::card-grid :::card{title="Community Forum" href="https://forum.weaviate.io/c/support" icon="messages-square"} Ask questions and connect with other developers on our **Community forum**. ::: :::: :::card{title="Support" href="/guides/support-overview" icon="life-buoy"} Weaviate Cloud user or customer? Find the right channel on the **Support page**. ::: \::: ## Related pages - [Agents](./agents-index.md) - [AI-assisted Weaviate code generation](./ai-assisted-vibe-coding-index.md) - [APIs](./apis-index.md) - [Authorization and authentication](./authorization-and-authentication-index.md) - [Benchmarks](./benchmarks-index.md) - [Best practices](./best-practices-index.md) - [Client libraries](./clients-index.md) - [Client Libraries / SDKs](./client-libraries-index.md) - [Cloud](./cloud-index.md) - [Cloud account management](./cloud-account-management-index.md) # Agent Instructions This portal answers questions programmatically. To receive a synthesized, source-cited answer instead of crawling page by page, append the `?ask=` query parameter to any page URL on this site: /guides/quickstart?ask=how+do+I+authenticate Optional parameters: - `&goal=` steers the answer toward your objective (e.g. `&goal=write+a+python+client`). - `&version=