Table of documentation contents

Additional properties

Introduction

GraphQL additional properties can be used on data objects in Get{} Queries to get additional information about the returned data objects. Which additional properties are available depends on the modules that are attached to Weaviate. The fields id, certainty, featureProjection and classification are available from Weaviate Core. On nested GraphQL fields (references to other data classes), only the id can be returned. Explanation on specific additional properties can be found on the module pages, see for example text2vec-contextionary.

id

The id field contains the unique uuid of the data object.

Certainty

When a semantic search is performed with the Get {} function (nearVector and nearText if the text2vec-contextionary or text2vec-transformers module is enabled), you can get the certainty of the returned data objects. The certainty value is a measure indicating how close the data object is to the search query. This is measured by the cosine similarity between the search query (the near... filter in the Get {} function) and the data object in the vector space. Results of GraphQL semantic search queries by the near... filter, will automatically be ordered with descending certainty values, so that the top results match your search query the most.

An example query:

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

🟢 Click here to try out this graphql example in the Weaviate Console.

Classification

When a data-object has been subjected to classification, you can get additional information about how the object was classified by running the following command:

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

🟢 Click here to try out this graphql example in the Weaviate Console.

Feature Projection

Because Weaviate stores all data in a vector space, you can visualize the results according to the results of your query. The feature projection is intended to reduce the dimensionality of the object’s vector into something easily suitable for visualizing, such as 2d or 3d. The underlying algorithm is exchangeable, the first algorithm to be provided is t-SNE.

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

ParameterTypeDefaultImplication
dimensionsint2Target dimensionality, usually 2 or 3
algorithmstringtsneAlgorithm to be used, currently supported: tsne
perplexityintmin(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
learningRateint25The t-SNE learning rate
iterationsint100The 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:

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

🟢 Click here to try out this graphql example in the Weaviate Console.

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

Weaviate T-SNE example

Best practices and notes

  • There is no request size limit (other than the global 10,000 items request limit) which can be used on a featureProjection query. However, due to the O(n^2) complexity of the t-SNE algorithm, large requests size have an exponential effect on the response time. We recommend to keep the request size at or below 100 items, as we have noticed drastic increases in response time thereafter.
  • Feature Projection happens in real-time, per query. The dimensions returned have no meaning across queries.
  • Currently only root elements (not resolved cross-references) are taken into consideration for the featureProjection.
  • 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.

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 issues: Github. Or,
  5. Ask your question in the Slack channel: Slack.
Tags
  • graphql
  • additional properties
  • additional
  • underscore