Table of documentation contents

Get

The Get{} function is Weaviate's bread and butter. It is the most direct way to access data.

Basics

  • Weaviate’s query language is GraphQL.
  • You can query a Weaviate after you’ve created a schema and populated it with data.
  • You can easily query a Weaviate by using the GraphQL interface inside a Weaviate Playground.
  • Some functions have (semantic) filters available.
  • An individual semantic kind (i.e., data object) can be collected through the RESTful API as well.

Introduction

The Get{} function is the most straight-ahead function Weaviate has. It is the most direct wat to collect data from a weaviate. Especially when you combine them with filters, you can easily browse your Weaviate.

Define a query

You can query Weaviate for semantic kinds based on standard GraphQL queries. The examples below only contain the GraphQL query. You can POST a GraphQL query to Weaviate as follows:

$ curl http://localhost/v1/graphql -X POST -H 'Content-type: application/json' -d '{GraphQL query}'

A GraphQL JSON object is defined as:

{
    "query": "{ # GRAPHQL QUERY }"
}

Get{} Function

Get{} query structure and syntax

The Get{} function is always defined based on the following principle:

{
  Get {
    <SematicKind> {
      <Class> {
        <property>
        <PropertyWithReference>
          ... on <ClassOfBeacon> {
            <property>
            _<underscore-property>
          }
      }
    }
  }
}

A Get{} function is always based on the schema. For example, if you’ve created a schema with a class Articles which has the properties name and publicationDate, you can query it as follows:

{
  Get {
    Things {
      Article {
        title
        url
        wordCount
      }
    }
  }
}

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

The above query will result in something like the following:

{
  "data": {
    "Get": {
      "Things": {
        "Article": [{
          "title": "“Joker” Is a Viewing Experience of Rare, Numbing Emptiness",
          "url": "https://www.newyorker.com/culture/the-front-row/joker-is-a-viewing-experience-of-rare-numbing-emptiness",
          "wordCount": 1794
        }]
      }
    }
  }
}

Work with graph beacons

If you’ve set a beacon reference in the schema, you can query it as follows:

{
  Get {
    Things {
      Article {
        title
        url
        wordCount
        InPublication {           # the reference
          ... on Publication {    # you always set the destination class
            name                  # the property related to target class
          }
        }
      }
    }
  }
}

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

Note that if you’ve set the cardinality to many, you might have multiple data types. For example:

{
  Get {
    Things {
      Article {
        title
        url
        wordCount
        HasAuthors {
          ... on Author {
            name
          }
          ... on Publication {
            name
          }
        }
      }
    }
  }
}

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

Filters

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

Underscore Properties

For every Get{} request you can get additional information about the returned data object(s) by using underscore-properties. You can recognize these properties because they are prefixed with an underscore and can be added to any GraphQL request.

Below you find an overview of available underscore-properties.

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: {} parameter 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 Playground.

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 Playground.

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 Playground.

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: { # <== optional, set the explore function
          concepts:["music"]
          moveTo: {
            concepts: ["beatles"]
            force: 0.5
          }
        }
      ){
        title
        _nearestNeighbors{
          neighbors {
            concept
            distance
          }
        }
      }
    }
  }
}

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

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: { # <== optional, set the explore function
          concepts:["music"]
          moveTo: {
            concepts: ["beatles"]
            force: 0.5
          }
        }
        limit: 12
      ){
        title
        _featureProjection{
          vector
        }
      }
    }
  }
}

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

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

Weaviate T-SNE example

The same example with the dimensions property for a 3D visualisation:

{
  Get{
    Things{
      Article(
        explore: { # <== optional, set the explore function
          concepts:["music"]
          moveTo: {
            concepts: ["beatles"]
            force: 0.5
          }
        }
        limit: 12
      ){
        title
        _featureProjection(
          dimensions: 3
        ){
          vector
        }
      }
    }
  }
}

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

Get RESTful Function

Underscore properties also have RESTful equivalents that can be retrieved by setting the _include= argument.

underscore propertyreturns
?include=_classificationClassification information
?include=_vectorThe vector how the dataobject is vectorized information
?include=_nearestNeighborsDisplay information about the neighboring concepts of an object
?include=_featureProjectionA feature projection intended to reduce the dimensionality of the object’s vector into something easily suitable for visualizing

More Resources

If you can’t find the answer to your question here, please use the:

  1. Knowledge base of old issues. Or,
  2. For questions: Stackoverflow. Or,
  3. For issues: Github.
  4. For Frequently Asked Questions.
Tags
  • Query
  • GraphQL