---
title: "Additional properties (metadata)"
description: "GraphQL API guide for accessing metadata and additional properties to enrich query results with extra context."
url: https://docs.weaviate.io/weaviate/api/graphql/additional-properties
---

# Additional properties (metadata)

> [!WARNING]
>
> **The GraphQL API is deprecated**
>
> Weaviate Cloud switches off the GraphQL API on **May 1, 2027**. Clusters that have not used GraphQL in the last 30 days have it switched off from December 1, 2026. New Weaviate Cloud clusters are already created with GraphQL disabled. Self-hosted Weaviate keeps GraphQL until at least May 1, 2027. The first minor release after that date disables it by default, and you can switch it back on. It is removed in a later release.
>
> Use a [client library](https://docs.weaviate.io/weaviate/client-libraries), the [web client](https://docs.weaviate.io/weaviate/client-libraries/typescript/web-client) or the REST Search API instead. See [Migrating from the GraphQL API](https://docs.weaviate.io/weaviate/api/graphql/migration).

Various 'additional properties', also called 'metadata', can be retrieved in queries.

### Available additional properties

The fields `id`, `vector`, `certainty`, `distance`, `featureProjection` and `classification` are available by default.

Further additional properties may be available for each query, depending on the query type as well as enabled Weaviate modules.

Note that only the `id` is available from cross-referenced objects.

### Requesting additional properties

In GraphQL queries, all additional properties to be retrieved can be set through the reserved `_additional{}` property.

Each of the client libraries may handle this differently. See the examples below.

### Usage example

An example query getting the [UUID](https://docs.weaviate.io/weaviate/api/graphql/additional-properties#id) and the [distance](https://docs.weaviate.io/weaviate/api/graphql/additional-properties#distance).

**Python**

```py
import weaviate
import weaviate.classes as wvc
import os

client = weaviate.connect_to_local()

try:
    articles = client.collections.use("Article")

    response = articles.query.near_text(
        query="fashion",
        limit=5,
        return_metadata=wvc.query.MetadataQuery(distance=True)
    )

    for o in response.objects:
        print(o.metadata.distance)  # Inspect metadata
        print(o.uuid)  # Inspect UUID (returned by default)
        print(o.properties)  # Inspect returned objects

finally:
    client.close()
```

**Go (v5)**

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

  className := "Article"
  fields := []graphql.Field{
    {Name: "title"},
    {Name: "_additional", Fields: []graphql.Field{
      {Name: "id"},
      {Name: "distance"},
    }},
  }

  explore := client.GraphQL().NearTextArgBuilder().
    WithConcepts([]string{"fashion"})
  ctx := context.Background()

  result, err := client.GraphQL().Get().
    WithClassName(className).
    WithFields(fields...).
    WithNearText(explore).
    Do(ctx)

  if err != nil {
    panic(err)
  }
  fmt.Printf("%v", result)
}
```

**Curl**

```bash
echo '{
  "query": "{
    Get {
      Article (
        nearText: {
          concepts: [\"fashion\"],
        }
      ) {
        title
        _additional {
          id
          distance
        }
      }
    }
  }"
}' | curl \
    -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer learn-weaviate' \
    -H "X-OpenAI-Api-Key: $OPENAI_API_KEY" \
    -d @- \
    https://edu-demo.weaviate.network/v1/graphql
```

**GraphQL**

```graphql
{
  Get {
    Article (
      nearText: {
        concepts: ["fashion"],
      }
    ) {
      title
      _additional {
        id
        distance
      }
    }
  }
}
```

**Expected response**

```json
{
  "data": {
    "Get": {
      "Article": [
        {
          "_additional": {
            "distance": 0.15422738,
            "id": "e76ec9ae-1b84-3995-939a-1365b2215312"
          },
          "title": "How to Dress Up For an Untraditional Holiday Season"
        },
        {
          "_additional": {
            "distance": 0.15683109,
            "id": "a2d51619-dd22-337a-8950-e1a407dab3d2"
          },
          "title": "2020's biggest fashion trends reflect a world in crisis"
        },
        ...
      ]
    }
  }
}
```

## Additional properties

### id

Use the `id` field to fetch the object [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier).

### vector

Use the `vector` field to fetch the vector embedding of the data object

### generate

> [!NOTE]
>
> **Requires a [generative model integration](https://docs.weaviate.io/weaviate/model-providers)**

The `generate` field can be used to perform [retrieval augmented generation](https://docs.weaviate.io/weaviate/search/generative).

A `generate` query will cause corresponding additional result fields to be available, such as `singleResult`, `groupedResult` and `error`.

For examples, see the [related how-to page](https://docs.weaviate.io/weaviate/search/generative).

### rerank

> [!NOTE]
>
> **Requires a [reranker integration](https://docs.weaviate.io/weaviate/model-providers)**

The `rerank` field can be used to [reorder the search results](https://docs.weaviate.io/weaviate/search/rerank). It accepts two parameters:

| Parameter | Required | Type | Description |
| - | - | - | - |
| `property` | yes | `string` | Which property to pass to the reranker. For example, you may want to run a similarity search on a Products collection, then rerank specifically on the Name field. |
| `query` | no | `string` | Optionally specify a different query. |

A `rerank` query will cause corresponding additional `score` field to be available.

For examples, see the [related how-to page](https://docs.weaviate.io/weaviate/search/rerank).

### creationTimeUnix

Use the `creationTimeUnix` field to fetch the data object creation timestamp.

### lastUpdateTimeUnix

Use the `lastUpdateTimeUnix` field to fetch the data object last updated timestamp.

### Vector search metadata

Use the `distance` or `certainty` field to fetch a vector similarity metric between the query vector and each result of a vector search.

#### Distance

`Distance` is the raw distance determined as part of the vector search, displayed in the same unit as the distance metric used.

See the full overview of [distance metrics and the expected distance ranges](https://docs.weaviate.io/weaviate/config-refs/distances#available-distance-metrics).

A lower value for a distance always means that two vectors are closer to one another than a higher value.

#### Certainty (only for cosine distance)

`Certainty` is an opinionated measure that always returns a number between 0 and 1. It is therefore only usable with fixed-range distance metrics, such as `cosine`.

### Keyword search metadata

Use the `score` and `explainScore` field to fetch the scores and explanations of each result of a keyword (BM25) search.

#### Score

The `score` will be the BM25F score of the result. Note that this score is relative to the dataset and query.

#### ExplainScore

The `explainScore` will explain the BM25F score of the result, broken down into its components. This can be used to understand why a result was scored the way it was.

### Hybrid search metadata

Use the `score` and `explainScore` field to fetch the scores and explanations of each result of a hybrid search.

#### Score

The `score` will be the hybrid score of the result, based on the nominated [fusion algorithm](https://docs.weaviate.io/weaviate/api/graphql/search-operators#fusion-algorithms). Note that this score is relative to the dataset and query.

#### ExplainScore

The `explainScore` will be the hybrid score of the result, broken down into its vector and keyword search components. This can be used to understand why a result was scored the way it was.

### Query profiling

> [!NOTE]
>
> **Added in `v1.36.9`**

Use `queryProfile` to get per-shard timing breakdowns for a search query. Profile data is returned on the response level (attached to the first result in GraphQL), not per object. It includes timing for vector search, keyword scoring, filter evaluation, and object retrieval, broken down by shard and cluster node.

In GraphQL, request `_additional { queryProfile }`. The profile is returned as a JSON string.

See [How-to: Query profiling](https://docs.weaviate.io/weaviate/search/query-profile) for full details, available metrics, and Python examples.

### Classification

When a data-object has been [subjected to classification](https://docs.weaviate.io/weaviate/api/rest#tag/classifications), you can get additional information about how the object was classified by running the following command:

**Python**

```python
import weaviate

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

near_text_filter = {
  "concepts": ["fashion"]
}

additional_props = {
  "classification" : ["basedOn", "classifiedFields", "completed", "id"]
}

query_result = (
  client.query
  .get("Article", "title")
  .with_additional(additional_props)
  .with_near_text(near_text_filter)
  .do()
)

print(query_result)
```

**Go (v5)**

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

  className := "Article"
  title := graphql.Field{Name: "title"}
  _additional := graphql.Field{Name: "_additional", Fields: []graphql.Field{
    {Name: "classification", Fields: []graphql.Field{
      {Name: "basedOn"},
      {Name: "classifiedFields"},
      {Name: "completed"},
      {Name: "completed"},
    }},
  }}

  ctx := context.Background()

  result, err := client.GraphQL().Get().
    WithClassName(className).
    WithFields(title, _additional).
    Do(ctx)

  if err != nil {
    panic(err)
  }
  fmt.Printf("%v", result)
}
```

**Curl**

```bash
echo '{
  "query": "{
    Get {
      Article (
        nearText: {
          concepts: [\"fashion\"],
        }
      ) {
        title
        _additional {
          classification {
            basedOn
            classifiedFields
            completed
            id
            scope
          }
        }
      }
    }
  }"
}' | curl \
    -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer learn-weaviate' \
    -H "X-OpenAI-Api-Key: $OPENAI_API_KEY" \
    -d @- \
    https://edu-demo.weaviate.network/v1/graphql
```

**GraphQL**

```graphql
{
  Get {
    Article (
      nearText: {
        concepts: ["fashion"],
      }
    ) {
      title
      _additional {
        classification {
          basedOn
          classifiedFields
          completed
          id
          scope
        }
      }
    }
  }
}
```

### Feature Projection

Use feature projection to reduce the results' vectors to 2d or 3d for easy visualization. Currently [t-SNE](https://en.wikipedia.org/wiki/T-distributed_stochastic_neighbor_embedding) is used.

To tweak the feature projection optional parameters (currently GraphQL-only) can be provided. The values and their defaults are:

| Parameter | Type | Default | Implication |
| - | - | - | - |
| `dimensions` | `int` | `2` | Target dimensionality, usually `2` or `3` |
| `algorithm` | `string` | `tsne` | Algorithm to be used, currently supported: `tsne` |
| `perplexity` | `int` | `min(5, len(results)-1)` | The `t-SNE` perplexity value, must be smaller than the `n-1` where `n` is the number of results to be visualized |
| `learningRate` | `int` | `25` | The `t-SNE` learning rate |
| `iterations` | `int` | `100` | The number of iterations the `t-SNE` algorithm runs. Higher values lead to more stable results at the cost of a larger response time |

An example with default settings:

**Python**

```python
import weaviate

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

near_text_filter = {
  "concepts": ["music"],
  "moveTo": {
    "concepts": ["beatles"],
    "force": 0.5
  }
}
additional_clause = {
  "featureProjection": [
    "vector"
  ]
}

additional_setting = {
  "dimensions": 2
}

query_result = (
  client.query
  .get("Article", "title")
  .with_near_text(near_text_filter)
  .with_additional(
    (additional_clause, additional_setting)
  )
  .do()
)
print(query_result)
```

**Go (v5)**

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

  className := "Article"
  fields := []graphql.Field{
    {Name: "title"},
    {Name: "_additional", Fields: []graphql.Field{
      {Name: "featureProjection(dimensions: 2)", Fields: []graphql.Field{
        {Name: "vector"},
      }},
    }},
  }
  concepts := []string{"music"}
  moveTo := &graphql.MoveParameters{
    Concepts: []string{"beatles"},
    Force:    0.5,
  }
  nearText := client.GraphQL().NearTextArgBuilder().
    WithConcepts(concepts).
    WithMoveTo(moveTo)
  ctx := context.Background()

  result, err := client.GraphQL().Get().
    WithClassName(className).
    WithFields(fields...).
    WithNearText(nearText).
    WithLimit(12).
    Do(ctx)

  if err != nil {
    panic(err)
  }
  fmt.Printf("%v", result)
}
```

**Curl**

```bash
echo '{
  "query": "{
    Get {
      Article (
        nearText:{
          concepts:[\"music\"],
          moveTo: {
            concepts: [\"beatles\"],
            force: 0.5
          }
        }
      ) {
        title
        _additional {
          featureProjection(dimensions: 2) {
            vector
          }
        }
      }
    }
  }"
}' | curl \
    -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer learn-weaviate' \
    -H "X-OpenAI-Api-Key: $OPENAI_API_KEY" \
    -d @- \
    https://edu-demo.weaviate.network/v1/graphql
```

**GraphQL**

```graphql
{
  Get {
    Article (
      nearText: {
        concepts:["music"],
        moveTo: {
          concepts: ["beatles"],
          force: 0.5
        }
      }
    ) {
      title
      _additional {
        featureProjection(dimensions: 2) {
          vector
        }
      }
    }
  }
}
```

**Expected response**

```json
{
  "data": {
    "Get": {
      "Article": [
        {
          "_additional": {
            "featureProjection": {
              "vector": [
                -115.17981,
                -16.873344
              ]
            }
          },
          "title": "Opinion | John Lennon Told Them \u2018Girls Don\u2019t Play Guitar.\u2019 He Was So Wrong."
        },
        {
          "_additional": {
            "featureProjection": {
              "vector": [
                -117.78348,
                -21.845968
              ]
            }
          },
          "title": "Opinion | John Lennon Told Them \u2018Girls Don\u2019t Play Guitar.\u2019 He Was So Wrong."
        },
        ...
      ]
    }
  }
}
```

The above result can be plotted as follows (where the result in red is the first result):

![Weaviate T-SNE example](https://docs.weaviate.io/assets/images/plot-noSettings-9def05b239633fd65cc5fbd5d5740006.png "Weaviate T-SNE example")

#### best practices and notes

- Due to the O(n^2) complexity of the `t-SNE` algorithm, we recommend to keep the request size at or below 100 items.
- `t-SNE` is non-deterministic and lossy, and happens in real-time per query. The dimensions returned have no meaning across queries.
- Due to the relatively high cost of the underlying algorithm, we recommend to limit requests including a `featureProjection` in high-load situations where response time matters. Avoid parallel requests including a `featureProjection`, so that some threads stay available to serve other, time-critical requests.