Table of documentation contents

Underscore properties

GraphQL underscore properties can be used in Get{} queries to get additional information about the returned data objects. You can recognize these properties because they are prefixed with an underscore. The value of underscore properties of data objects can be for example be used to enhance interpretability of semantic searches and classification, or for projection and visualization.

Interpretation

When Weaviate vectorizes your data-object, it normalizes the data so that the contextionary can interpret it. With the _interpretation underscore property you can request how Weaviate indexed your data-object.

  {
  Get {
    Things {
      Article {
        _interpretation {
          source {
            concept
            occurrence
            weight
          }
        }
        summary
      }
    }
  }
}

๐ŸŸข Click here to try out this graphql example in the Weaviate Console.

Semantic Path

The semantic path returns an array of concepts from the query to the data object. This allows you to see which steps Weaviate took and how the query and data object are interpreted.

PropertyDescription
conceptthe concept that is found in this step.
distanceToNextthe distance to the next step (null for the last step).
distanceToPreviousthis distance to the previous step (null for the first step).
distanceToQuerythe distance of this step to the query.
distanceToResultthe distance of the step to this result.

Note: Building a semantic path is only possible if an explore: {} filter is set. As the explore term represents the beginning of the path and each search result represents the end of the path. Since explore:{} queries are currently exclusively possible in GraphQL, the _semanticPath is therefore not available in the REST API.

Example: showing a semantic path without edges.

  {
  Get{
    Things{
      Publication(
        explore: {
          concepts: ["fashion"],
          certainty: 0.7,
          moveAwayFrom: {
            concepts: ["finance"],
            force: 0.45
          },
          moveTo: {
            concepts: ["haute couture"],
            force: 0.85
          }
        }
      ){
        name
        _semanticPath{
          path {
            concept
            distanceToNext
            distanceToPrevious
            distanceToQuery
            distanceToResult
          }
        }
      }
    }
  }
}

๐ŸŸข 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 {
    Things {
      Article {
        _classification {
          basedOn
          classifiedFields
          completed
          id
          scope
        }
      }
    }
  }
}

๐ŸŸข Click here to try out this graphql example in the Weaviate Console.

Nearest Neighbors

The nearest neighbors underscore property displays the nearest concepts to the object in the search results. You can use it in combination will all other search filters but you donโ€™t have to.

  {
  Get{
    Things{
      Article(
        explore: {
          concepts:["music"],
          moveTo: {
            concepts: ["beatles"],
            force: 0.5
          }
        }
      ){
        title
        _nearestNeighbors{
          neighbors {
            concept
            distance
          }
        }
      }
    }
  }
}

๐ŸŸข 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 paramaters (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{
    Things{
      Article(
        explore: {
          concepts:["music"],
          moveTo: {
            concepts: ["beatles"],
            force: 0.5
          }
        }
        limit: 12
      ){
        title
        _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
  • underscore properties
  • underscore