Core Knowledge
Getting started

Installation
Configuration
Client libraries

Schema

GraphQL references
RESTful API references

Modules

Architecture
Vector Index (ANN) Plugins
Benchmarks

Tutorials
More resources

Vector search parameters

Weaviate on Stackoverflow badge Weaviate issues on Github badge Weaviate v1.15.1 version badge Weaviate v1.15.1 version badge Weaviate total Docker pulls badge

​Vector search parameters allow you to conduct specific vector search operations. Some are built into Weaviate directly, and others are enabled through Weaviate modules.


Setting search parameters

Vector search parameters are added to GraphQL queries on the class level.

For example:

{
  Get{
    Class (
      filter: {
        variables: values
      }
    ){
      property
    }
  }
}

Built-in parameters

B​uilt in search parameters are available in all Weaviate instances and don’t require any modules.​

NearVector

This filter allows you to find data objects in the vicinity of an input vector. It’s supported by the Get{} function.

  • Note: this argument is different from the GraphQL Explore{} function )
  • Note: Cannot use multiple 'near' arguments, or a 'near' argument along with an 'ask' filter

Variables

VariablesMandatoryTypeDescription
vectoryes[float]This variable takes a vector embedding in the form of an array of floats. The array should have the same length as the vectors in this class.
distancenofloatThe required degree of similarity between an object’s characteristics and the provided filter values. Can’t be used together with the certainty variable. The interpretation of the value of the distance field depends on the distance metric used.
certaintynofloatNormalized Distance between the result item and the search vector. Normalized to be between 0 (identical vectors) and 1 (perfect opposite).. Can’t be used together with the distance variable.

Example

  {
  Get{
    Publication(
      nearVector: {
        vector: [-0.36840257,0.13973749,-0.28994447,-0.18607682,0.20019795,0.15541431,-0.42353877,0.30262852,0.2724561,0.07069917,0.4877447,0.038771532,0.64523,-0.15907241,-0.3413626,-0.026682584,-0.63310874,-0.33411884,0.082939014,0.30305764,0.045918174,-0.21439327,-0.5005205,0.6210859,-0.2729049,-0.51221114,0.09680918,0.094923325,-0.15688285,-0.07325482,0.6588305,0.0523736,-0.14173415,-0.27428055,0.25526586,0.057506185,-0.3103442,0.028601522,0.124522656,0.66984487,0.12160647,-0.5090515,-0.540393,-0.39546522,-0.2201204,0.34625968,-0.21068871,0.21132985,0.048714135,0.09043683,0.3176081,-0.056684002,-0.12117501,-0.6591976,-0.26731065,0.42615625,0.33333477,-0.3240578,-0.18771006,0.2328068,-0.17239179,-0.33583146,-0.6556605,-0.10608161,-0.5135395,-0.25123677,-0.23004892,0.7036331,0.04456794,0.41253626,0.27872285,-0.28226635,0.11927197,-0.4677766,0.4343466,-0.17538455,0.10621233,0.95815116,0.23587844,-0.006406698,-0.10512518,-1.1125883,-0.37921682,0.040789194,0.676718,0.3369762,0.040712647,0.580487,0.20063736,-0.021220192,-0.09071747,-0.0023735985,0.30007777,-0.039925132,0.4035474,-0.2518212,-0.17846306,0.12371392,-0.0703354,-0.3752431,-0.652917,0.5952828,1.3426708,-0.08167235,-0.38515738,0.058423538,-0.08100355,-0.192886,0.3745164,-0.23291737,0.33326542,-0.6019264,-0.42822492,-0.6524583,-0.15210791,-0.5073593,0.022548754,-0.058033653,-0.47369233,-0.30890635,0.6338296,0.0017854869,0.1954949,0.99348027,-0.26558784,-0.058124136,1.149388,0.02915948,0.013422121,0.25484946,-0.030017598,-0.23879935,0.053123385,-0.36463016,-0.0024245526,0.1202083,-0.45966506,-0.34140104,-0.08484162,-0.03537422,-0.2817959,0.25044164,-0.5060605,0.1252808,-0.032539487,0.110069446,-0.20679846,-0.46421885,-0.4141739,0.26994973,-0.070687145,0.16862138,-0.20162229,0.22199251,-0.2771402,0.23653336,0.16585203,-0.08286354,-0.15343396,0.23893964,-0.7453282,-0.16549355,-0.1947069,0.46136436,0.22064126,0.28654936,-0.038697664,0.037633028,-0.80988157,0.5094175,-0.0920082,0.25405347,-0.64169943,0.43366328,-0.2999211,-0.4090591,0.11957859,0.00803617,-0.0433745,0.12818244,0.28464508,-0.31760025,0.16558012,-0.33553946,-0.3943465,0.59569097,-0.6524206,0.3683173,-0.60456693,0.2046492,0.46010277,0.24695799,0.2946015,0.11376746,-0.027988048,0.03749422,-0.16577742,0.23407385,-0.0231737,-0.023245076,0.08752677,0.2299883,0.35467404,0.046193745,-0.39828986,0.21079691,0.38396686,-0.0018698421,0.16047359,-0.057517264,-0.203534,0.23438136,-0.84250915,0.22371331,0.0058325706,0.30733636,0.19518353,-0.108008966,0.6509316,0.070131645,-0.24023099,0.28779706,0.2326336,0.07004021,-0.45955566,0.20426086,-0.37472793,-0.049604423,0.4537271,0.6133582,-1.0527759,-0.5472505,0.15193434,0.5296606,-0.11560251,0.07279209,0.40557706,0.2505283,0.24490519,0.017602902,-0.004647707,0.16608049,0.12576887,0.118216865,0.4403996,0.39552462,-0.22196701,-0.061155193,0.03693534,-0.4022908,0.3842317,-0.0831345,0.01930883,0.3446575,-0.2167439,-0.23994556,-0.09370326,-0.3671856,0.044011243,0.017895095,-0.019855855,-0.16416992,0.17858285,0.31287143,0.38368022,-0.006513525,0.45780763,-0.23027879,0.108570844,-0.4449492,-0.035763215,0.03818417,0.040017277,-0.17022872,-0.2622464,0.65610534,0.16720143,0.2515769,-0.23535803,0.62484455,0.16771325,-0.62404263,0.19176348,-0.72786695,0.18485649,-0.30914405,-0.3230534,-0.24064465,0.28841522,0.39792386,0.15618932,0.03928854,0.18277727,-0.101632096,0.1868196,-0.33366352,0.086561844,0.48557812,-0.6198209,-0.07978742]
      }
    ){
      name
      _additional {
        certainty
      }
    }
  }
}
  import weaviate

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

nearVector = {
  'vector': [-0.36840257,0.13973749,-0.28994447,-0.18607682,0.20019795,0.15541431,-0.42353877,0.30262852,0.2724561,0.07069917,0.4877447,0.038771532,0.64523,-0.15907241,-0.3413626,-0.026682584,-0.63310874,-0.33411884,0.082939014,0.30305764,0.045918174,-0.21439327,-0.5005205,0.6210859,-0.2729049,-0.51221114,0.09680918,0.094923325,-0.15688285,-0.07325482,0.6588305,0.0523736,-0.14173415,-0.27428055,0.25526586,0.057506185,-0.3103442,0.028601522,0.124522656,0.66984487,0.12160647,-0.5090515,-0.540393,-0.39546522,-0.2201204,0.34625968,-0.21068871,0.21132985,0.048714135,0.09043683,0.3176081,-0.056684002,-0.12117501,-0.6591976,-0.26731065,0.42615625,0.33333477,-0.3240578,-0.18771006,0.2328068,-0.17239179,-0.33583146,-0.6556605,-0.10608161,-0.5135395,-0.25123677,-0.23004892,0.7036331,0.04456794,0.41253626,0.27872285,-0.28226635,0.11927197,-0.4677766,0.4343466,-0.17538455,0.10621233,0.95815116,0.23587844,-0.006406698,-0.10512518,-1.1125883,-0.37921682,0.040789194,0.676718,0.3369762,0.040712647,0.580487,0.20063736,-0.021220192,-0.09071747,-0.0023735985,0.30007777,-0.039925132,0.4035474,-0.2518212,-0.17846306,0.12371392,-0.0703354,-0.3752431,-0.652917,0.5952828,1.3426708,-0.08167235,-0.38515738,0.058423538,-0.08100355,-0.192886,0.3745164,-0.23291737,0.33326542,-0.6019264,-0.42822492,-0.6524583,-0.15210791,-0.5073593,0.022548754,-0.058033653,-0.47369233,-0.30890635,0.6338296,0.0017854869,0.1954949,0.99348027,-0.26558784,-0.058124136,1.149388,0.02915948,0.013422121,0.25484946,-0.030017598,-0.23879935,0.053123385,-0.36463016,-0.0024245526,0.1202083,-0.45966506,-0.34140104,-0.08484162,-0.03537422,-0.2817959,0.25044164,-0.5060605,0.1252808,-0.032539487,0.110069446,-0.20679846,-0.46421885,-0.4141739,0.26994973,-0.070687145,0.16862138,-0.20162229,0.22199251,-0.2771402,0.23653336,0.16585203,-0.08286354,-0.15343396,0.23893964,-0.7453282,-0.16549355,-0.1947069,0.46136436,0.22064126,0.28654936,-0.038697664,0.037633028,-0.80988157,0.5094175,-0.0920082,0.25405347,-0.64169943,0.43366328,-0.2999211,-0.4090591,0.11957859,0.00803617,-0.0433745,0.12818244,0.28464508,-0.31760025,0.16558012,-0.33553946,-0.3943465,0.59569097,-0.6524206,0.3683173,-0.60456693,0.2046492,0.46010277,0.24695799,0.2946015,0.11376746,-0.027988048,0.03749422,-0.16577742,0.23407385,-0.0231737,-0.023245076,0.08752677,0.2299883,0.35467404,0.046193745,-0.39828986,0.21079691,0.38396686,-0.0018698421,0.16047359,-0.057517264,-0.203534,0.23438136,-0.84250915,0.22371331,0.0058325706,0.30733636,0.19518353,-0.108008966,0.6509316,0.070131645,-0.24023099,0.28779706,0.2326336,0.07004021,-0.45955566,0.20426086,-0.37472793,-0.049604423,0.4537271,0.6133582,-1.0527759,-0.5472505,0.15193434,0.5296606,-0.11560251,0.07279209,0.40557706,0.2505283,0.24490519,0.017602902,-0.004647707,0.16608049,0.12576887,0.118216865,0.4403996,0.39552462,-0.22196701,-0.061155193,0.03693534,-0.4022908,0.3842317,-0.0831345,0.01930883,0.3446575,-0.2167439,-0.23994556,-0.09370326,-0.3671856,0.044011243,0.017895095,-0.019855855,-0.16416992,0.17858285,0.31287143,0.38368022,-0.006513525,0.45780763,-0.23027879,0.108570844,-0.4449492,-0.035763215,0.03818417,0.040017277,-0.17022872,-0.2622464,0.65610534,0.16720143,0.2515769,-0.23535803,0.62484455,0.16771325,-0.62404263,0.19176348,-0.72786695,0.18485649,-0.30914405,-0.3230534,-0.24064465,0.28841522,0.39792386,0.15618932,0.03928854,0.18277727,-0.101632096,0.1868196,-0.33366352,0.086561844,0.48557812,-0.6198209,-0.07978742]
}

result = (
  client.query
  .get("Publication", "name")
  .with_additional('certainty')
  .with_near_vector(nearVector)
  .do()
)

print(result)
  const weaviate = require("weaviate-client");

const client = weaviate.client({
  scheme: 'http',
  host: 'localhost:8080',
});

client.graphql
      .get()
      .withClassName('Publication')
      .withFields('name _additional {certainty}}')
      .withNearVector({vector: [-0.36840257,0.13973749,-0.28994447,-0.18607682,0.20019795,0.15541431,-0.42353877,0.30262852,0.2724561,0.07069917,0.4877447,0.038771532,0.64523,-0.15907241,-0.3413626,-0.026682584,-0.63310874,-0.33411884,0.082939014,0.30305764,0.045918174,-0.21439327,-0.5005205,0.6210859,-0.2729049,-0.51221114,0.09680918,0.094923325,-0.15688285,-0.07325482,0.6588305,0.0523736,-0.14173415,-0.27428055,0.25526586,0.057506185,-0.3103442,0.028601522,0.124522656,0.66984487,0.12160647,-0.5090515,-0.540393,-0.39546522,-0.2201204,0.34625968,-0.21068871,0.21132985,0.048714135,0.09043683,0.3176081,-0.056684002,-0.12117501,-0.6591976,-0.26731065,0.42615625,0.33333477,-0.3240578,-0.18771006,0.2328068,-0.17239179,-0.33583146,-0.6556605,-0.10608161,-0.5135395,-0.25123677,-0.23004892,0.7036331,0.04456794,0.41253626,0.27872285,-0.28226635,0.11927197,-0.4677766,0.4343466,-0.17538455,0.10621233,0.95815116,0.23587844,-0.006406698,-0.10512518,-1.1125883,-0.37921682,0.040789194,0.676718,0.3369762,0.040712647,0.580487,0.20063736,-0.021220192,-0.09071747,-0.0023735985,0.30007777,-0.039925132,0.4035474,-0.2518212,-0.17846306,0.12371392,-0.0703354,-0.3752431,-0.652917,0.5952828,1.3426708,-0.08167235,-0.38515738,0.058423538,-0.08100355,-0.192886,0.3745164,-0.23291737,0.33326542,-0.6019264,-0.42822492,-0.6524583,-0.15210791,-0.5073593,0.022548754,-0.058033653,-0.47369233,-0.30890635,0.6338296,0.0017854869,0.1954949,0.99348027,-0.26558784,-0.058124136,1.149388,0.02915948,0.013422121,0.25484946,-0.030017598,-0.23879935,0.053123385,-0.36463016,-0.0024245526,0.1202083,-0.45966506,-0.34140104,-0.08484162,-0.03537422,-0.2817959,0.25044164,-0.5060605,0.1252808,-0.032539487,0.110069446,-0.20679846,-0.46421885,-0.4141739,0.26994973,-0.070687145,0.16862138,-0.20162229,0.22199251,-0.2771402,0.23653336,0.16585203,-0.08286354,-0.15343396,0.23893964,-0.7453282,-0.16549355,-0.1947069,0.46136436,0.22064126,0.28654936,-0.038697664,0.037633028,-0.80988157,0.5094175,-0.0920082,0.25405347,-0.64169943,0.43366328,-0.2999211,-0.4090591,0.11957859,0.00803617,-0.0433745,0.12818244,0.28464508,-0.31760025,0.16558012,-0.33553946,-0.3943465,0.59569097,-0.6524206,0.3683173,-0.60456693,0.2046492,0.46010277,0.24695799,0.2946015,0.11376746,-0.027988048,0.03749422,-0.16577742,0.23407385,-0.0231737,-0.023245076,0.08752677,0.2299883,0.35467404,0.046193745,-0.39828986,0.21079691,0.38396686,-0.0018698421,0.16047359,-0.057517264,-0.203534,0.23438136,-0.84250915,0.22371331,0.0058325706,0.30733636,0.19518353,-0.108008966,0.6509316,0.070131645,-0.24023099,0.28779706,0.2326336,0.07004021,-0.45955566,0.20426086,-0.37472793,-0.049604423,0.4537271,0.6133582,-1.0527759,-0.5472505,0.15193434,0.5296606,-0.11560251,0.07279209,0.40557706,0.2505283,0.24490519,0.017602902,-0.004647707,0.16608049,0.12576887,0.118216865,0.4403996,0.39552462,-0.22196701,-0.061155193,0.03693534,-0.4022908,0.3842317,-0.0831345,0.01930883,0.3446575,-0.2167439,-0.23994556,-0.09370326,-0.3671856,0.044011243,0.017895095,-0.019855855,-0.16416992,0.17858285,0.31287143,0.38368022,-0.006513525,0.45780763,-0.23027879,0.108570844,-0.4449492,-0.035763215,0.03818417,0.040017277,-0.17022872,-0.2622464,0.65610534,0.16720143,0.2515769,-0.23535803,0.62484455,0.16771325,-0.62404263,0.19176348,-0.72786695,0.18485649,-0.30914405,-0.3230534,-0.24064465,0.28841522,0.39792386,0.15618932,0.03928854,0.18277727,-0.101632096,0.1868196,-0.33366352,0.086561844,0.48557812,-0.6198209,-0.07978742]})
      .do()
      .then(res => {
        console.log(res)
      })
      .catch(err => {
        console.error(err)
      });
  package main

import (
  "context"
  "fmt"

  "github.com/semi-technologies/weaviate-go-client/v4/weaviate"
  "github.com/semi-technologies/weaviate-go-client/v4/weaviate/graphql"
)

func main() {
  cfg := weaviate.Config{
    Host:   "localhost:8080",
    Scheme: "http",
  }
  client := weaviate.New(cfg)

  className := "Publication"

  name := graphql.Field{Name: "name"}
  _additional := graphql.Field{
    Name: "_additional", Fields: []graphql.Field{
      {Name: "certainty"},  // only supported if distance==cosine
      {Name: "distance"},   // always supported
    },
  }

  nearVector := client.GraphQL().NearVectorArgBuilder().
    WithVector([]float32{-0.36840257, 0.13973749, -0.28994447, -0.18607682, 0.20019795, 0.15541431, -0.42353877, 0.30262852, 0.2724561, 0.07069917, 0.4877447, 0.038771532, 0.64523, -0.15907241, -0.3413626, -0.026682584, -0.63310874, -0.33411884, 0.082939014, 0.30305764, 0.045918174, -0.21439327, -0.5005205, 0.6210859, -0.2729049, -0.51221114, 0.09680918, 0.094923325, -0.15688285, -0.07325482, 0.6588305, 0.0523736, -0.14173415, -0.27428055, 0.25526586, 0.057506185, -0.3103442, 0.028601522, 0.124522656, 0.66984487, 0.12160647, -0.5090515, -0.540393, -0.39546522, -0.2201204, 0.34625968, -0.21068871, 0.21132985, 0.048714135, 0.09043683, 0.3176081, -0.056684002, -0.12117501, -0.6591976, -0.26731065, 0.42615625, 0.33333477, -0.3240578, -0.18771006, 0.2328068, -0.17239179, -0.33583146, -0.6556605, -0.10608161, -0.5135395, -0.25123677, -0.23004892, 0.7036331, 0.04456794, 0.41253626, 0.27872285, -0.28226635, 0.11927197, -0.4677766, 0.4343466, -0.17538455, 0.10621233, 0.95815116, 0.23587844, -0.006406698, -0.10512518, -1.1125883, -0.37921682, 0.040789194, 0.676718, 0.3369762, 0.040712647, 0.580487, 0.20063736, -0.021220192, -0.09071747, -0.0023735985, 0.30007777, -0.039925132, 0.4035474, -0.2518212, -0.17846306, 0.12371392, -0.0703354, -0.3752431, -0.652917, 0.5952828, 1.3426708, -0.08167235, -0.38515738, 0.058423538, -0.08100355, -0.192886, 0.3745164, -0.23291737, 0.33326542, -0.6019264, -0.42822492, -0.6524583, -0.15210791, -0.5073593, 0.022548754, -0.058033653, -0.47369233, -0.30890635, 0.6338296, 0.0017854869, 0.1954949, 0.99348027, -0.26558784, -0.058124136, 1.149388, 0.02915948, 0.013422121, 0.25484946, -0.030017598, -0.23879935, 0.053123385, -0.36463016, -0.0024245526, 0.1202083, -0.45966506, -0.34140104, -0.08484162, -0.03537422, -0.2817959, 0.25044164, -0.5060605, 0.1252808, -0.032539487, 0.110069446, -0.20679846, -0.46421885, -0.4141739, 0.26994973, -0.070687145, 0.16862138, -0.20162229, 0.22199251, -0.2771402, 0.23653336, 0.16585203, -0.08286354, -0.15343396, 0.23893964, -0.7453282, -0.16549355, -0.1947069, 0.46136436, 0.22064126, 0.28654936, -0.038697664, 0.037633028, -0.80988157, 0.5094175, -0.0920082, 0.25405347, -0.64169943, 0.43366328, -0.2999211, -0.4090591, 0.11957859, 0.00803617, -0.0433745, 0.12818244, 0.28464508, -0.31760025, 0.16558012, -0.33553946, -0.3943465, 0.59569097, -0.6524206, 0.3683173, -0.60456693, 0.2046492, 0.46010277, 0.24695799, 0.2946015, 0.11376746, -0.027988048, 0.03749422, -0.16577742, 0.23407385, -0.0231737, -0.023245076, 0.08752677, 0.2299883, 0.35467404, 0.046193745, -0.39828986, 0.21079691, 0.38396686, -0.0018698421, 0.16047359, -0.057517264, -0.203534, 0.23438136, -0.84250915, 0.22371331, 0.0058325706, 0.30733636, 0.19518353, -0.108008966, 0.6509316, 0.070131645, -0.24023099, 0.28779706, 0.2326336, 0.07004021, -0.45955566, 0.20426086, -0.37472793, -0.049604423, 0.4537271, 0.6133582, -1.0527759, -0.5472505, 0.15193434, 0.5296606, -0.11560251, 0.07279209, 0.40557706, 0.2505283, 0.24490519, 0.017602902, -0.004647707, 0.16608049, 0.12576887, 0.118216865, 0.4403996, 0.39552462, -0.22196701, -0.061155193, 0.03693534, -0.4022908, 0.3842317, -0.0831345, 0.01930883, 0.3446575, -0.2167439, -0.23994556, -0.09370326, -0.3671856, 0.044011243, 0.017895095, -0.019855855, -0.16416992, 0.17858285, 0.31287143, 0.38368022, -0.006513525, 0.45780763, -0.23027879, 0.108570844, -0.4449492, -0.035763215, 0.03818417, 0.040017277, -0.17022872, -0.2622464, 0.65610534, 0.16720143, 0.2515769, -0.23535803, 0.62484455, 0.16771325, -0.62404263, 0.19176348, -0.72786695, 0.18485649, -0.30914405, -0.3230534, -0.24064465, 0.28841522, 0.39792386, 0.15618932, 0.03928854, 0.18277727, -0.101632096, 0.1868196, -0.33366352, 0.086561844, 0.48557812, -0.6198209, -0.07978742})

  ctx := context.Background()
  result, err := client.GraphQL().Get().
    WithClassName(className).
    WithFields(name, _additional).
    WithNearVector(nearVector).
    Do(ctx)

  if err != nil {
    panic(err)
  }
  fmt.Printf("%v", result)
}
  package technology.semi.weaviate;

import technology.semi.weaviate.client.Config;
import technology.semi.weaviate.client.WeaviateClient;
import technology.semi.weaviate.client.base.Result;
import technology.semi.weaviate.client.v1.graphql.model.GraphQLResponse;
import technology.semi.weaviate.client.v1.graphql.query.argument.NearVectorArgument;
import technology.semi.weaviate.client.v1.graphql.query.fields.Field;

public class App {
  public static void main(String[] args) {
    Config config = new Config("http", "localhost:8080");
    WeaviateClient client = new WeaviateClient(config);

    String className = "Publication";
    Field title = Field.builder().name("title").build();
    Field _additional = Field.builder()
      .name("_additional")
      .fields(new Field[]{
        Field.builder().name("certainty").build()  // only supported if distance==cosine
        Field.builder().name("distance").build()   // always supported
      }).build();

    Float[] vector = new Float[]{-0.36840257f,0.13973749f,-0.28994447f,-0.18607682f,0.20019795f,0.15541431f,-0.42353877f,0.30262852f,0.2724561f,0.07069917f,0.4877447f,0.038771532f,0.64523f,-0.15907241f,-0.3413626f,-0.026682584f,-0.63310874f,-0.33411884f,0.082939014f,0.30305764f,0.045918174f,-0.21439327f,-0.5005205f,0.6210859f,-0.2729049f,-0.51221114f,0.09680918f,0.094923325f,-0.15688285f,-0.07325482f,0.6588305f,0.0523736f,-0.14173415f,-0.27428055f,0.25526586f,0.057506185f,-0.3103442f,0.028601522f,0.124522656f,0.66984487f,0.12160647f,-0.5090515f,-0.540393f,-0.39546522f,-0.2201204f,0.34625968f,-0.21068871f,0.21132985f,0.048714135f,0.09043683f,0.3176081f,-0.056684002f,-0.12117501f,-0.6591976f,-0.26731065f,0.42615625f,0.33333477f,-0.3240578f,-0.18771006f,0.2328068f,-0.17239179f,-0.33583146f,-0.6556605f,-0.10608161f,-0.5135395f,-0.25123677f,-0.23004892f,0.7036331f,0.04456794f,0.41253626f,0.27872285f,-0.28226635f,0.11927197f,-0.4677766f,0.4343466f,-0.17538455f,0.10621233f,0.95815116f,0.23587844f,-0.006406698f,-0.10512518f,-1.1125883f,-0.37921682f,0.040789194f,0.676718f,0.3369762f,0.040712647f,0.580487f,0.20063736f,-0.021220192f,-0.09071747f,-0.0023735985f,0.30007777f,-0.039925132f,0.4035474f,-0.2518212f,-0.17846306f,0.12371392f,-0.0703354f,-0.3752431f,-0.652917f,0.5952828f,1.3426708f,-0.08167235f,-0.38515738f,0.058423538f,-0.08100355f,-0.192886f,0.3745164f,-0.23291737f,0.33326542f,-0.6019264f,-0.42822492f,-0.6524583f,-0.15210791f,-0.5073593f,0.022548754f,-0.058033653f,-0.47369233f,-0.30890635f,0.6338296f,0.0017854869f,0.1954949f,0.99348027f,-0.26558784f,-0.058124136f,1.149388f,0.02915948f,0.013422121f,0.25484946f,-0.030017598f,-0.23879935f,0.053123385f,-0.36463016f,-0.0024245526f,0.1202083f,-0.45966506f,-0.34140104f,-0.08484162f,-0.03537422f,-0.2817959f,0.25044164f,-0.5060605f,0.1252808f,-0.032539487f,0.110069446f,-0.20679846f,-0.46421885f,-0.4141739f,0.26994973f,-0.070687145f,0.16862138f,-0.20162229f,0.22199251f,-0.2771402f,0.23653336f,0.16585203f,-0.08286354f,-0.15343396f,0.23893964f,-0.7453282f,-0.16549355f,-0.1947069f,0.46136436f,0.22064126f,0.28654936f,-0.038697664f,0.037633028f,-0.80988157f,0.5094175f,-0.0920082f,0.25405347f,-0.64169943f,0.43366328f,-0.2999211f,-0.4090591f,0.11957859f,0.00803617f,-0.0433745f,0.12818244f,0.28464508f,-0.31760025f,0.16558012f,-0.33553946f,-0.3943465f,0.59569097f,-0.6524206f,0.3683173f,-0.60456693f,0.2046492f,0.46010277f,0.24695799f,0.2946015f,0.11376746f,-0.027988048f,0.03749422f,-0.16577742f,0.23407385f,-0.0231737f,-0.023245076f,0.08752677f,0.2299883f,0.35467404f,0.046193745f,-0.39828986f,0.21079691f,0.38396686f,-0.0018698421f,0.16047359f,-0.057517264f,-0.203534f,0.23438136f,-0.84250915f,0.22371331f,0.0058325706f,0.30733636f,0.19518353f,-0.108008966f,0.6509316f,0.070131645f,-0.24023099f,0.28779706f,0.2326336f,0.07004021f,-0.45955566f,0.20426086f,-0.37472793f,-0.049604423f,0.4537271f,0.6133582f,-1.0527759f,-0.5472505f,0.15193434f,0.5296606f,-0.11560251f,0.07279209f,0.40557706f,0.2505283f,0.24490519f,0.017602902f,-0.004647707f,0.16608049f,0.12576887f,0.118216865f,0.4403996f,0.39552462f,-0.22196701f,-0.061155193f,0.03693534f,-0.4022908f,0.3842317f,-0.0831345f,0.01930883f,0.3446575f,-0.2167439f,-0.23994556f,-0.09370326f,-0.3671856f,0.044011243f,0.017895095f,-0.019855855f,-0.16416992f,0.17858285f,0.31287143f,0.38368022f,-0.006513525f,0.45780763f,-0.23027879f,0.108570844f,-0.4449492f,-0.035763215f,0.03818417f,0.040017277f,-0.17022872f,-0.2622464f,0.65610534f,0.16720143f,0.2515769f,-0.23535803f,0.62484455f,0.16771325f,-0.62404263f,0.19176348f,-0.72786695f,0.18485649f,-0.30914405f,-0.3230534f,-0.24064465f,0.28841522f,0.39792386f,0.15618932f,0.03928854f,0.18277727f,-0.101632096f,0.1868196f,-0.33366352f,0.086561844f,0.48557812f,-0.6198209f,-0.07978742f};
    NearVectorArgument nearVector = NearVectorArgument.builder()
      .vector(vector)
      .build();

    Result<GraphQLResponse> result = client.graphQL().get()
      .withClassName(className)
      .withFields(title, _additional)
      .withNearVector(nearVector)
      .run();

    if (result.hasErrors()) {
      System.out.println(result.getError());
      return;
    }
    System.out.println(result.getResult());
  }
}
  $ echo '{ 
  "query": "{
    Get{
      Publication(
        nearVector: {
          vector: [-0.36840257,0.13973749,-0.28994447,-0.18607682,0.20019795,0.15541431,-0.42353877,0.30262852,0.2724561,0.07069917,0.4877447,0.038771532,0.64523,-0.15907241,-0.3413626,-0.026682584,-0.63310874,-0.33411884,0.082939014,0.30305764,0.045918174,-0.21439327,-0.5005205,0.6210859,-0.2729049,-0.51221114,0.09680918,0.094923325,-0.15688285,-0.07325482,0.6588305,0.0523736,-0.14173415,-0.27428055,0.25526586,0.057506185,-0.3103442,0.028601522,0.124522656,0.66984487,0.12160647,-0.5090515,-0.540393,-0.39546522,-0.2201204,0.34625968,-0.21068871,0.21132985,0.048714135,0.09043683,0.3176081,-0.056684002,-0.12117501,-0.6591976,-0.26731065,0.42615625,0.33333477,-0.3240578,-0.18771006,0.2328068,-0.17239179,-0.33583146,-0.6556605,-0.10608161,-0.5135395,-0.25123677,-0.23004892,0.7036331,0.04456794,0.41253626,0.27872285,-0.28226635,0.11927197,-0.4677766,0.4343466,-0.17538455,0.10621233,0.95815116,0.23587844,-0.006406698,-0.10512518,-1.1125883,-0.37921682,0.040789194,0.676718,0.3369762,0.040712647,0.580487,0.20063736,-0.021220192,-0.09071747,-0.0023735985,0.30007777,-0.039925132,0.4035474,-0.2518212,-0.17846306,0.12371392,-0.0703354,-0.3752431,-0.652917,0.5952828,1.3426708,-0.08167235,-0.38515738,0.058423538,-0.08100355,-0.192886,0.3745164,-0.23291737,0.33326542,-0.6019264,-0.42822492,-0.6524583,-0.15210791,-0.5073593,0.022548754,-0.058033653,-0.47369233,-0.30890635,0.6338296,0.0017854869,0.1954949,0.99348027,-0.26558784,-0.058124136,1.149388,0.02915948,0.013422121,0.25484946,-0.030017598,-0.23879935,0.053123385,-0.36463016,-0.0024245526,0.1202083,-0.45966506,-0.34140104,-0.08484162,-0.03537422,-0.2817959,0.25044164,-0.5060605,0.1252808,-0.032539487,0.110069446,-0.20679846,-0.46421885,-0.4141739,0.26994973,-0.070687145,0.16862138,-0.20162229,0.22199251,-0.2771402,0.23653336,0.16585203,-0.08286354,-0.15343396,0.23893964,-0.7453282,-0.16549355,-0.1947069,0.46136436,0.22064126,0.28654936,-0.038697664,0.037633028,-0.80988157,0.5094175,-0.0920082,0.25405347,-0.64169943,0.43366328,-0.2999211,-0.4090591,0.11957859,0.00803617,-0.0433745,0.12818244,0.28464508,-0.31760025,0.16558012,-0.33553946,-0.3943465,0.59569097,-0.6524206,0.3683173,-0.60456693,0.2046492,0.46010277,0.24695799,0.2946015,0.11376746,-0.027988048,0.03749422,-0.16577742,0.23407385,-0.0231737,-0.023245076,0.08752677,0.2299883,0.35467404,0.046193745,-0.39828986,0.21079691,0.38396686,-0.0018698421,0.16047359,-0.057517264,-0.203534,0.23438136,-0.84250915,0.22371331,0.0058325706,0.30733636,0.19518353,-0.108008966,0.6509316,0.070131645,-0.24023099,0.28779706,0.2326336,0.07004021,-0.45955566,0.20426086,-0.37472793,-0.049604423,0.4537271,0.6133582,-1.0527759,-0.5472505,0.15193434,0.5296606,-0.11560251,0.07279209,0.40557706,0.2505283,0.24490519,0.017602902,-0.004647707,0.16608049,0.12576887,0.118216865,0.4403996,0.39552462,-0.22196701,-0.061155193,0.03693534,-0.4022908,0.3842317,-0.0831345,0.01930883,0.3446575,-0.2167439,-0.23994556,-0.09370326,-0.3671856,0.044011243,0.017895095,-0.019855855,-0.16416992,0.17858285,0.31287143,0.38368022,-0.006513525,0.45780763,-0.23027879,0.108570844,-0.4449492,-0.035763215,0.03818417,0.040017277,-0.17022872,-0.2622464,0.65610534,0.16720143,0.2515769,-0.23535803,0.62484455,0.16771325,-0.62404263,0.19176348,-0.72786695,0.18485649,-0.30914405,-0.3230534,-0.24064465,0.28841522,0.39792386,0.15618932,0.03928854,0.18277727,-0.101632096,0.1868196,-0.33366352,0.086561844,0.48557812,-0.6198209,-0.07978742]
        }
      ){
        name
        _additional {
          certainty  // only supported if distance==cosine
          distance   // always supported
        }
      }
    }
  }"
}' | curl \
    -X POST \
    -H 'Content-Type: application/json' \
    -d @- \
    http://localhost:8080/v1/graphql

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

Additional information

If the distance metric is cosine you can also use certainty instead of distance. Certainty normalizes the distance in a range of 0..1, where 0 reprents a perfect opposite (cosine distance of 2) and 1 represents vectors with an identical angle (cosine distance of 0). Certainty is not available on non-cosine distance metrics.

NearObject

This filter allows you to find data objects in the vicinity of other data objects by UUID. It’s supported by the Get{} function.

  • Note: You cannot use multiple near<Media> arguments, or a near<Media> argument along with an ask argument.
  • Note: You can specify an object’s id or beacon in the argument, along with a desired certainty.
  • Note that the first result will always be the object in the filter itself.
  • Near object search can also be combined with text2vec modules.

Variables

VariablesMandatoryTypeDescription
idyesUUIDData object identifier in the uuid format.
beaconyesurlData object identifier in the beacon URL format. E.g., weaviate://<hostname>/<kind>/id.
distancenofloatThe required degree of similarity between an object’s characteristics and the provided filter values. Can’t be used together with the certainty variable. The interpretation of the value of the distance field depends on the distance metric used.
certaintynofloatNormalized Distance between the result item and the search vector. Normalized to be between 0 (identical vectors) and 1 (perfect opposite).. Can’t be used together with the distance variable.

Example

  {
  Get{
    Publication(
      nearObject: {
        id: "e5dc4a4c-ef0f-3aed-89a3-a73435c6bbcf", # or weaviate://localhost/e5dc4a4c-ef0f-3aed-89a3-a73435c6bbcf
        distance: 0.6 # prior to v1.14, use certainty: 0.7
      }
    ){
      name
      _additional {
        certainty # only works if distance==cosine
        distance  # always works
      }
    }
  }
}
  import weaviate

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

nearObject = {"id": "e5dc4a4c-ef0f-3aed-89a3-a73435c6bbcf"} # or {"beacon": "weaviate://localhost/e5dc4a4c-ef0f-3aed-89a3-a73435c6bbcf"}

result = (
  client.query
  .get("Publication", ["name", "_additional {certainty distance}"]) # certainty only supported if distance==cosine
  .with_near_object(nearObject)
  .do()
)

print(result)
  const weaviate = require("weaviate-client");

const client = weaviate.client({
  scheme: 'http',
  host: 'localhost:8080',
});

client.graphql
      .get()
      .withClassName('Publication')
      .withFields('name _additional {certainty distance}}') # certainty only supported if distance==cosine
      .withNearObject({id: "e5dc4a4c-ef0f-3aed-89a3-a73435c6bbcf"})
      .do()
      .then(res => {
        console.log(res)
      })
      .catch(err => {
        console.error(err)
      });
  package main

import (
  "context"
  "fmt"

  "github.com/semi-technologies/weaviate-go-client/v4/weaviate"
  "github.com/semi-technologies/weaviate-go-client/v4/weaviate/graphql"
)

func main() {
  cfg := weaviate.Config{
    Host:   "localhost:8080",
    Scheme: "http",
  }
  client := weaviate.New(cfg)

  className := "Publication"
  fields := []graphql.Field{
    {Name: "name"},
    {Name: "_additional", Fields: []graphql.Field{
      {Name: "certainty"}, // certainty only supported if distance==cosine
      {Name: "distance"},  // distance always supported
    }},
  }
  nearObject := client.GraphQL().NearObjectArgBuilder().WithID("e5dc4a4c-ef0f-3aed-89a3-a73435c6bbcf")
  ctx := context.Background()

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

  if err != nil {
    panic(err)
  }
  fmt.Printf("%v", result)
}
  package technology.semi.weaviate;

import technology.semi.weaviate.client.Config;
import technology.semi.weaviate.client.WeaviateClient;
import technology.semi.weaviate.client.base.Result;
import technology.semi.weaviate.client.v1.graphql.model.GraphQLResponse;
import technology.semi.weaviate.client.v1.graphql.query.argument.NearObjectArgument;
import technology.semi.weaviate.client.v1.graphql.query.fields.Field;

public class App {
  public static void main(String[] args) {
    Config config = new Config("http", "localhost:8080");
    WeaviateClient client = new WeaviateClient(config);

    String className = "Publication";
    Field name = Field.builder().name("name").build();
    Field _additional = Field.builder()
      .name("_additional")
      .fields(new Field[]{
        Field.builder().name("certainty").build(), // only supported if distance==cosine
        Field.builder().name("distance").build()   // always supported
      }).build();

    NearObjectArgument nearObject = client.graphQL().arguments().nearObjectArgBuilder()
      .id("e5dc4a4c-ef0f-3aed-89a3-a73435c6bbcf")
      .build();

    Result<GraphQLResponse> result = client.graphQL().get()
      .withClassName(className)
      .withFields(name, _additional)
      .withNearObject(nearObject)
      .run();

    if (result.hasErrors()) {
      System.out.println(result.getError());
      return;
    }
    System.out.println(result.getResult());
  }
}
  $ echo '{ 
  "query": "{
    Get{
      Publication(
        nearObject: {
          id: "e5dc4a4c-ef0f-3aed-89a3-a73435c6bbcf",
          distance: 0.6 # prior to v1.14 use certainty instead of distance 
        }
      ){
        name
        _additional {
          certainty # only supported if distance==cosine
          distance  # always supported
        }
      }
    }
  }"
}' | curl \
    -X POST \
    -H 'Content-Type: application/json' \
    -d @- \
    http://localhost:8080/v1/graphql

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

Group

You can use a group operator to combine similar concepts (aka entity merging). There are two ways of grouping objects with a semantic similarity together.

Variables

VariablesMandatoryTypeDescription
typeyesclosest, merge​You can only show the closest concept (closest) or merge all similar entities into one single string (merge).
forceyesurlThe force to apply for a particular movements. Must be between 0 and 1 where 0 is equivalent to no movement and 1 is equivalent to largest movement possible.

Example

  {
  Get {
    Publication(
      group:{
        type: merge,
        force:0.05
      }
    ) {
      name
    }
  }
}
  import weaviate

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

get_articles_group = """
  {
    Get {
      Publication(
        group:{
          type: merge,
          force:0.05
        }
      ) {
        name
      }
    }
  }
"""

query_result = client.query.raw(get_articles_group)
print(query_result)
  const weaviate = require("weaviate-client");

const client = weaviate.client({
  scheme: 'http',
  host: 'localhost:8080',
});

client.graphql
      .get()
      .withClassName('Publication')
      .withFields('name')
      .withGroup({
        type: "merge",
        force: 0.05
      })
      .do()
      .then(res => {
        console.log(res)
      })
      .catch(err => {
        console.error(err)
      });
  package main

import (
  "context"
  "fmt"

  "github.com/semi-technologies/weaviate-go-client/v4/weaviate"
  "github.com/semi-technologies/weaviate-go-client/v4/weaviate/graphql"
)

func main() {
  cfg := weaviate.Config{
    Host:   "localhost:8080",
    Scheme: "http",
  }
  client := weaviate.New(cfg)

  name := graphql.Field{Name: "name"}
  group := client.GraphQL().GroupArgBuilder().WithType(graphql.Merge).WithForce(0.05)

  result, err := client.GraphQL().Get().
    WithClassName("Publication").
    WithFields(name).
    WithGroup(group).
    Do(context.Background())

  if err != nil {
    panic(err)
  }
  fmt.Printf("%v", result)
}
  package technology.semi.weaviate;

import technology.semi.weaviate.client.Config;
import technology.semi.weaviate.client.WeaviateClient;
import technology.semi.weaviate.client.base.Result;
import technology.semi.weaviate.client.v1.graphql.model.GraphQLResponse;
import technology.semi.weaviate.client.v1.graphql.query.argument.GroupArgument;
import technology.semi.weaviate.client.v1.graphql.query.argument.GroupType;
import technology.semi.weaviate.client.v1.graphql.query.fields.Field;

public class App {
  public static void main(String[] args) {
    Config config = new Config("http", "localhost:8080");
    WeaviateClient client = new WeaviateClient(config);

    Field name = Field.builder().name("name").build();
    GroupArgument group = GroupArgument.builder()
      .type(GroupType.merge)
      .force(0.05f)
      .build();

    Result<GraphQLResponse> result = client.graphQL().get()
      .withClassName("Publication")
      .withFields(name)
      .withGroup(group)
      .run();

    if (result.hasErrors()) {
      System.out.println(result.getError());
      return;
    }
    System.out.println(result.getResult());
  }
}
  $ echo '{ 
  "query": "{
    Get {
      Publication(
        group:{
          type: merge,
          force:0.05
        }
      ) {
        name
      }
    }
  }"
}' | curl \
    -X POST \
    -H 'Content-Type: application/json' \
    -d @- \
    http://localhost:8080/v1/graphql

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

This results in the following. Note that publications International New York Times, The New York Times Company and New York Times are merged. The property values that do not have an exact overlap will all be shown, with the value of the most central concept before the brackets.

{
  "data": {
    "Get": {
      "Publication": [
        {
          "name": "Vogue"
        },
        {
          "name": "Wired"
        },
        {
          "name": "Financial Times"
        },
        {
          "name": "New Yorker"
        },
        {
          "name": "The Economist"
        },
        {
          "name": "International New York Times (The New York Times Company, New York Times)"
        },
        {
          "name": "Wall Street Journal"
        },
        {
          "name": "CNN"
        },
        {
          "name": "Game Informer"
        },
        {
          "name": "The Guardian"
        },
        {
          "name": "Fox News"
        }
      ]
    }
  },
  "errors": null
}

Module specific parameters

Module specific search parameters are made available in certain Weaviate modules.​

NearText

Enabled by the modules: text2vec-openai, text2vec-transformers, text2vec-contextionary.

This filter allows you to find data objects in the vicinity of the vector representation of a single or multiple concepts. It’s supported by the Get{} function.

Variables

VariablesMandatoryTypeDescription
conceptsyes[string]An array of strings, this can be natural language queries or single words. If multiple strings are used, a centroid is calculated and used. Learn more about how the concepts are parsed here
certaintynofloatThe required degree of similarity between an object’s characteristics and the provided filter values.
distancenofloatNormalized Distance between the result item and the search vector. Normalized to be between 0 (identical vectors) and 1 (perfect opposite).
autocorrectnobooleanAutocorrect input text values
moveTonoobject{}Move your search term closer to another vector described by keywords
moveTo{concepts}no[string]An array of strings, this can be natural language queries or single words. If multiple strings are used, a centroid is calculated and used.
moveTo{objects}no[UUID]Object IDs to move the results to. This is used to “bias” NLP search results into a certain direction in vector space
moveTo{force}nofloatThe force to apply for a particular movements. Must be between 0 and 1 where 0 is equivalent to no movement and 1 is equivalent to largest movement possible
moveAwayFromnoobject{}Move your search term away from another vector described by keywords
moveAwayFrom{concepts}no[string]An array of strings, this can be natural language queries or single words. If multiple strings are used, a centroid is calculated and used.
moveAwayFrom{objects}no[UUID]Object IDs to move the results to. This is used to “bias” NLP search results into a certain direction in vector space
moveAwayFrom{force}nofloatThe force to apply for a particular movements. Must be between 0 and 1 where 0 is equivalent to no movement and 1 is equivalent to largest movement possible
distancenofloatThe required degree of similarity between an object’s characteristics and the provided filter values. Can’t be used together with the certainty variable. The interpretation of the value of the distance field depends on the distance metric used.
certaintynofloatNormalized Distance between the result item and the search vector. Normalized to be between 0 (identical vectors) and 1 (perfect opposite).. Can’t be used together with the distance variable.

Example I

This example shows a basic overview of using the nearText filter.

  {
  Get{
    Publication(
      nearText: {
        concepts: ["fashion"],
        distance: 0.6 # prior to v1.14 use "certainty" instead of "distance"
        moveAwayFrom: {
          concepts: ["finance"],
          force: 0.45
        },
        moveTo: {
          concepts: ["haute couture"],
          force: 0.85
        }
      }
    ){
      name
      _additional {
        certainty # only supported if distance==cosine.
        distance  # always supported
      }
    }
  }
}
  import weaviate

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

nearText = {
  "concepts": ["fashion"],
  "distance": 0.6, # prior to v1.14 use "certainty" instead of "distance"
  "moveAwayFrom": {
    "concepts": ["finance"],
    "force": 0.45
  },
  "moveTo": {
    "concepts": ["haute couture"],
    "force": 0.85
  }
}

result = (
  client.query
  .get("Publication", ["name", "_additional {certainty distance} "]) # note that certainty is only supported if distance==cosine
  .with_near_text(nearText)
  .do()
)

print(result)
  const weaviate = require("weaviate-client");

const client = weaviate.client({
  scheme: 'http',
  host: 'localhost:8080',
});

client.graphql
  .get()
  .withClassName('Publication')
  .withFields('name _additional{certainty distance}') // note that certainty is only supported if distance==cosine
  .withNearText({
    concepts: ["fashion"],
    distance: 0.6, // prior to v1.14 use certainty instead of distance
    moveAwayFrom: {
      concepts: ["finance"],
      force: 0.45
    },
    moveTo: {
      concepts: ["haute couture"],
      force: 0.85
    }
  })
  .do()
  .then(console.log)
  .catch(console.error);
  package main

import (
  "context"
  "fmt"

  "github.com/semi-technologies/weaviate-go-client/v4/weaviate"
  "github.com/semi-technologies/weaviate-go-client/v4/weaviate/graphql"
)

func main() {
  cfg := weaviate.Config{
    Host:   "localhost:8080",
    Scheme: "http",
  }
  client := weaviate.New(cfg)

  className := "Publication"

  name := graphql.Field{Name: "name"}
  _additional := graphql.Field{
    Name: "_additional", Fields: []graphql.Field{
      {Name: "certainty"}, // only supported if distance==cosine
      {Name: "distance"},  // always supported
    },
  }

  concepts := []string{"fashion"}
  distance := float32(0.6)
  moveAwayFrom := &graphql.MoveParameters{
    Concepts: []string{"finance"},
    Force:    0.45,
  }
  moveTo := &graphql.MoveParameters{
    Concepts: []string{"haute couture"},
    Force:    0.85,
  }
  nearText := client.GraphQL().NearTextArgBuilder().
    WithConcepts(concepts).
    WithDistance(distance). // use WithCertainty(certainty) prior to v1.14
    WithMoveTo(moveTo).
    WithMoveAwayFrom(moveAwayFrom)

  ctx := context.Background()

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

  if err != nil {
    panic(err)
  }
  fmt.Printf("%v", result)
}
  package technology.semi.weaviate;

import technology.semi.weaviate.client.Config;
import technology.semi.weaviate.client.WeaviateClient;
import technology.semi.weaviate.client.base.Result;
import technology.semi.weaviate.client.v1.graphql.model.GraphQLResponse;
import technology.semi.weaviate.client.v1.graphql.query.argument.NearTextArgument;
import technology.semi.weaviate.client.v1.graphql.query.argument.NearTextMoveParameters;
import technology.semi.weaviate.client.v1.graphql.query.fields.Field;

public class App {
  public static void main(String[] args) {
    Config config = new Config("http", "localhost:8080");
    WeaviateClient client = new WeaviateClient(config);

    NearTextMoveParameters moveTo = NearTextMoveParameters.builder()
      .concepts(new String[]{ "haute couture" }).force(0.85f).build();

    NearTextMoveParameters moveAway = NearTextMoveParameters.builder()
      .concepts(new String[]{ "finance" }).force(0.45f)
      .build();

    NearTextArgument nearText = client.graphQL().arguments().nearTextArgBuilder()
      .concepts(new String[]{ "fashion" })
      .distance(0.6f) // use .certainty(0.7f) prior to v1.14
      .moveTo(moveTo)
      .moveAwayFrom(moveAway)
      .build();

    Field name = Field.builder().name("name").build();
    Field _additional = Field.builder()
      .name("_additional")
      .fields(new Field[]{
        Field.builder().name("certainty").build(), // only supported if distance==cosine
        Field.builder().name("distance").build(),  // always supported
      }).build();

    Result<GraphQLResponse> result = client.graphQL().get()
      .withClassName("Publication")
      .withFields(name, _additional)
      .withNearText(nearText)
      .run();

    if (result.hasErrors()) {
      System.out.println(result.getError());
      return;
    }
    System.out.println(result.getResult());
  }
}
  $ echo '{
  "query": "{
    Get{
      Publication(
        nearText: {
          concepts: [\"fashion\"],
          distance: 0.6, // use certainty instead of distance prior to v1.14
          moveAwayFrom: {
            concepts: [\"finance\"],
            force: 0.45
          },
          moveTo: {
            concepts: [\"haute couture\"],
            force: 0.85
          }
        }
      ){
        name
        _additional {
          certainty // only supported if distance==cosine
          distance  // always supported
        }
      }
    }
  }"
}' | curl \
    -X POST \
    -H 'Content-Type: application/json' \
    -d @- \
    http://localhost:8080/v1/graphql

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

Example II

You can also bias results toward other data objects’ vector representations. For example, in this dataset, we have an ambiguous query on our news article dataset, which we bias towards an article called: “Tohoku: A Japan destination for all seasons.”

  {
  Get{
    Article(
      nearText: {
        concepts: ["traveling in Asia"],
        certainty: 0.7,
        moveTo: {
          objects: [{
            # this ID is of the article:
            # "Tohoku: A Japan destination for all seasons."
            id: "2faf2b7d-f185-30c0-8c80-a01b7cfeefb4"
          }]
          force: 0.85
        }
      }
    ){
      title
      summary
      _additional {
        certainty
      }
    }
  }
}
  import weaviate

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

nearText = {
  "concepts": ["traveling in Asia"],
  "certainty": 0.7,
  "moveTo": {
    "objects": [{'id': "2faf2b7d-f185-30c0-8c80-a01b7cfeefb4"}],
    "force": 0.85
  }
}

result = (
  client.query
  .get("Article", ["title", "summary", "_additional { certainty }"])
  .with_near_text(nearText)
  .do()
)

print(result)
  const weaviate = require("weaviate-client");

const client = weaviate.client({
  scheme: 'http',
  host: 'localhost:8080',
});

client.graphql
  .get()
  .withClassName('Article')
  .withFields("title summary _additional { certainty }")
  .withNearText({
    concepts: ["traveling in Asia"],
    certainty: 0.7,
    moveTo: {
      // this ID is of the article: "Tohoku: A Japan destination for all seasons."
      objects: [{ id: "2faf2b7d-f185-30c0-8c80-a01b7cfeefb4" }],
      force: 0.85
    }
  })
  .do()
  .then(console.log)
  .catch(console.error);
  package main

import (
  "context"
  "fmt"

  "github.com/semi-technologies/weaviate-go-client/v4/weaviate"
  "github.com/semi-technologies/weaviate-go-client/v4/weaviate/graphql"
)

func main() {
  cfg := weaviate.Config{
    Host:   "localhost:8080",
    Scheme: "http",
  }
  client := weaviate.New(cfg)

  className := "Article"

  title := graphql.Field{Name: "title"}
  summary := graphql.Field{Name: "summary"}
  _additional := graphql.Field{
    Name: "_additional", Fields: []graphql.Field{
      {Name: "certainty"},
    },
  }

  concepts := []string{"traveling in Asia"}
  certainty := float32(0.7)
  moveTo := &graphql.MoveParameters{
    Objects: []graphql.MoverObject{
	  // this ID is of the article: "Tohoku: A Japan destination for all seasons."
      {ID: "2faf2b7d-f185-30c0-8c80-a01b7cfeefb4"},
    },
    Force: 0.85,
  }
  nearText := client.GraphQL().NearTextArgBuilder().
    WithConcepts(concepts).
    WithCertainty(certainty).
    WithMoveTo(moveTo)

  ctx := context.Background()

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

  if err != nil {
    panic(err)
  }
  fmt.Printf("%v", result)
}
  package technology.semi.weaviate;

import technology.semi.weaviate.client.Config;
import technology.semi.weaviate.client.WeaviateClient;
import technology.semi.weaviate.client.base.Result;
import technology.semi.weaviate.client.v1.graphql.model.GraphQLResponse;
import technology.semi.weaviate.client.v1.graphql.query.argument.NearTextArgument;
import technology.semi.weaviate.client.v1.graphql.query.argument.NearTextMoveParameters;
import technology.semi.weaviate.client.v1.graphql.query.fields.Field;

public class App {
  public static void main(String[] args) {
    Config config = new Config("http", "localhost:8080");
    WeaviateClient client = new WeaviateClient(config);

    NearTextMoveParameters moveTo = NearTextMoveParameters.builder()
      .objects(new NearTextMoveParameters.ObjectMove[]{
        // this ID is of the article: "Tohoku: A Japan destination for all seasons."
        NearTextMoveParameters.ObjectMove.builder().id("2faf2b7d-f185-30c0-8c80-a01b7cfeefb4").build()
      })
      .force(0.85f)
      .build();

    NearTextArgument nearText = client.graphQL().arguments().nearTextArgBuilder()
      .concepts(new String[]{ "traveling in Asia" })
      .certainty(0.7f)
      .moveTo(moveTo)
      .build();

    Field title = Field.builder().name("title").build();
    Field summary = Field.builder().name("summary").build();
    Field _additional = Field.builder()
      .name("_additional")
      .fields(new Field[]{
        Field.builder().name("certainty").build(),
      }).build();

    Result<GraphQLResponse> result = client.graphQL().get()
      .withClassName("Article")
      .withFields(title, summary, _additional)
      .withNearText(nearText)
      .run();

    if (result.hasErrors()) {
      System.out.println(result.getError());
      return;
    }
    System.out.println(result.getResult());
  }
}
  $ echo '{
  Get{
    Article(
      nearText: {
        concepts: [\"traveling in Asia\"],
        certainty: 0.7,
        moveTo: {
          objects: [{
            # this ID is of the article:
            # "Tohoku: A Japan destination for all seasons."
            id: \"2faf2b7d-f185-30c0-8c80-a01b7cfeefb4\"
          }]
          force: 0.85
        }
      }
    ){
      title
      summary
      _additional {
        certainty
      }
    }
  }
}' | curl \
    -X POST \
    -H 'Content-Type: application/json' \
    -d @- \
    http://localhost:8080/v1/graphql

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

Additional information

Distance metrics

If the distance metric is cosine you can also use certainty instead of distance. Certainty normalizes the distance in a range of 0..1, where 0 reprents a perfect opposite (cosine distance of 2) and 1 represents vectors with an identical angle (cosine distance of 0). Certainty is not available on non-cosine distance metrics.

Concept parsing

Strings written in the concepts array are your fuzzy search terms. An array of concepts is required to set in the Explore query, and all words in this array should be present in the Contextionary.

There are three ways to define the concepts array argument in the filter.

  • ["New York Times"] = one vector position is determined based on the occurrences of the words
  • ["New", "York", "Times"] = all concepts have a similar weight.
  • ["New York", "Times"] = a combination of the two above.

A practical example would be: concepts: ["beatles", "John Lennon"]

Semantic Path

  • Only available in txt2vec-contextionary module

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 a nearText: {} filter is set as the explore term represents the beginning of the path and each search result represents the end of the path. Since nearText: {} 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 {
    Publication (
      nearText:{ 
          concepts: ["fashion"],
          distance: 0.6, #prior to v1.14 use certainty: 0.7
          moveAwayFrom: {
            concepts: ["finance"],
            force: 0.45
          },
          moveTo: {
            concepts: ["haute couture"],
            force: 0.85
          }
      }
    ) {
      name
      _additional {
        semanticPath{
          path {
            concept
            distanceToNext
            distanceToPrevious
            distanceToQuery
            distanceToResult
          }
        }
      }
    }
  }
}
  import weaviate

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

near_text_filter = {
  'concepts': ["fashion"],
  'distance': 0.6, #prior to v1.14 use certainty: 0.7
  'moveAwayFrom': {
    'concepts': ["finance"],
    'force': 0.45
  },
  'moveTo': {
    'concepts': ["haute couture"],
    'force': 0.85
  }
}

additional_props = {
  'semanticPath': 'path {distanceToNext distanceToPrevious distanceToQuery distanceToResult}'
} 

query_result = (
  client.query
  .get('Publication', 'name')
  .with_additional(additional_props)
  .with_near_text(near_text_filter)
  .do()
)

print(query_result)
  const weaviate = require("weaviate-client");

const client = weaviate.client({
  scheme: 'http',
  host: 'localhost:8080',
});

client.graphql
      .get()
      .withClassName('Publication')
      .withFields('name _additional { semanticPath{ path {concept distanceToNext distanceToPrevious distanceToQuery distanceToResult}}}')
      .withNearText({
        concepts: ["fashion"],
        distance: 0.6, #prior to v1.14 use certainty: 0.7
        moveAwayFrom: {
          concepts: ["finance"],
          force: 0.45
        },
        moveTo: {
          concepts: ["haute couture"],
          force: 0.85
        }
      })
      .do()
      .then(res => {
        console.log(res)
      })
      .catch(err => {
        console.error(err)
      });
  package main

import (
  "context"
  "fmt"

  "github.com/semi-technologies/weaviate-go-client/v4/weaviate"
  "github.com/semi-technologies/weaviate-go-client/v4/weaviate/graphql"
)

func main() {
  cfg := weaviate.Config{
    Host:   "localhost:8080",
    Scheme: "http",
  }
  client := weaviate.New(cfg)

  className := "Publication"
  fields := []graphql.Field{
    {Name: "name"},
    {Name: "_additional", Fields: []graphql.Field{
      {Name: "semanticPath", Fields: []graphql.Field{
        {Name: "path", Fields: []graphql.Field{
          {Name: "concept"},
          {Name: "distanceToNext"},
          {Name: "distanceToPrevious"},
          {Name: "distanceToQuery"},
          {Name: "distanceToResult"},
        }},
      }},
    }},
  }

  concepts := []string{"fashion"}
  moveTo := &graphql.MoveParameters{
    Concepts: []string{"haute couture"},
    Force:    0.85,
  }
  moveAwayFrom := &graphql.MoveParameters{
    Concepts: []string{"finance"},
    Force:    0.45,
  }
  nearText := client.GraphQL().NearTextArgBuilder().
    WithConcepts(concepts).
    WithDistance(0.6). // prior to v1.14, use WithCertainty(0.7)
    WithMoveTo(moveTo).
    WithMoveAwayFrom(moveAwayFrom)

  ctx := context.Background()

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

  if err != nil {
    panic(err)
  }
  fmt.Printf("%v", result)
}
  package technology.semi.weaviate;

import technology.semi.weaviate.client.Config;
import technology.semi.weaviate.client.WeaviateClient;
import technology.semi.weaviate.client.base.Result;
import technology.semi.weaviate.client.v1.graphql.model.GraphQLResponse;
import technology.semi.weaviate.client.v1.graphql.query.argument.NearTextArgument;
import technology.semi.weaviate.client.v1.graphql.query.argument.NearTextMoveParameters;
import technology.semi.weaviate.client.v1.graphql.query.fields.Field;

public class App {
  public static void main(String[] args) {
    Config config = new Config("http", "localhost:8080");
    WeaviateClient client = new WeaviateClient(config);

    Field name = Field.builder().name("name").build();
    Field _additional = Field.builder()
      .name("_additional")
      .fields(new Field[]{
        Field.builder()
          .name("semanticPath")
          .fields(new Field[]{
            Field.builder()
              .name("path")
              .fields(new Field[]{
                Field.builder().name("concept").build(),
                Field.builder().name("distanceToNext").build(),
                Field.builder().name("distanceToPrevious").build(),
                Field.builder().name("distanceToQuery").build(),
                Field.builder().name("distanceToResult").build()
              })
              .build()
          }).build()
      }).build();

    NearTextMoveParameters moveTo = NearTextMoveParameters.builder()
      .concepts(new String[]{ "haute couture" }).force(0.85f).build();

    NearTextMoveParameters moveAway = NearTextMoveParameters.builder()
      .concepts(new String[]{ "finance" }).force(0.45f)
      .build();

    NearTextArgument explore = client.graphQL().arguments().nearTextArgBuilder()
      .concepts(new String[]{ "fashion" })
      .distance(0.6f) // prior to v1.14, use .certainty(0.7f)
      .moveTo(moveTo)
      .moveAwayFrom(moveAway)
      .build();

    Result<GraphQLResponse> result = client.graphQL().get()
      .withClassName("Publication")
      .withFields(name, _additional)
      .withNearText(explore)
      .run();

    if (result.hasErrors()) {
      System.out.println(result.getError());
      return;
    }
    System.out.println(result.getResult());
  }
}
  $ echo '{ 
  "query": "{
    Get {
      Publication (
        nearText:{ 
            concepts: [\"fashion\"],
            distance: 0.6, #prior to v1.14 use certainty: 0.7
            moveAwayFrom: {
              concepts: [\"finance\"],
              force: 0.45
            },
            moveTo: {
              concepts: [\"haute couture\"],
              force: 0.85
            }
        }
      ) {
        name
        _additional {
          semanticPath{
            path {
              concept
              distanceToNext
              distanceToPrevious
              distanceToQuery
              distanceToResult
            }
          }
        }
      }
    }
  }"
}' | curl \
    -X POST \
    -H 'Content-Type: application/json' \
    -d @- \
    http://localhost:8080/v1/graphql

Ask

Enabled by the module: Question Answering.

This filter allows you to return answers to questions by running the results through a Q&A model.

Variables

VariablesMandatoryTypeDescription
questionyesstringThe question to be answered.
certaintynofloatDesired minimal certainty or confidence of answer to the question. The higher the value, the stricter the search becomes. The lower the value, the fuzzier the search becomes. If no certainty is set, any answer that could be extracted will be returned
propertiesno[string]The properties of the queries Class which contains text. If no properties are set, all are considered.
reranknobooleanIf enabled, the qna module will rerank the result based on the answer score. For example, if the 3rd result - as determined by the previous (semantic) search contained the most likely answer, result 3 will be pushed to position 1, etc. Not supported prior to v1.10.0

Example

  {
  Get {
    Article(
      ask: {
        question: "Who is the king of the Netherlands?",
        properties: ["summary"],
        rerank: false # supported from v1.10.0 on
      }, 
      limit: 1
    ) {
      title
      _additional {
        answer {
          hasAnswer
          certainty
          property
          result
          startPosition
          endPosition
        }
      }
    }
  }
}
  import weaviate

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

ask = {
  "question": "Who is the king of the Netherlands?",
  "properties": ["summary"]
}

result = (
  client.query
  .get("Article", ["title", "_additional {answer {hasAnswer certainty property result startPosition endPosition} }"])
  .with_ask(ask)
  .with_limit(1)
  .do()
)

print(result)
  const weaviate = require("weaviate-client");

const client = weaviate.client({
  scheme: 'http',
  host: 'localhost:8080',
});

client.graphql
      .get()
      .withClassName('Article')
      .withAsk({
        question: "Who is the king of the Netherlands?",
        properties: ["summary"],
      })
      .withFields('title _additional { answer { hasAnswer certainty property result startPosition endPosition } }')
      .withLimit(1)
      .do()
      .then(res => {
        console.log(res)
      })
      .catch(err => {
        console.error(err)
      });
  package main

import (
  "context"
  "fmt"

  "github.com/semi-technologies/weaviate-go-client/v4/weaviate"
  "github.com/semi-technologies/weaviate-go-client/v4/weaviate/graphql"
)

func main() {
  cfg := weaviate.Config{
    Host:   "localhost:8080",
    Scheme: "http",
  }
  client := weaviate.New(cfg)

  className := "Article"
  fields := []graphql.Field{
    {Name: "title"},
    {Name: "_additional", Fields: []graphql.Field{
      {Name: "answer", Fields: []graphql.Field{
        {Name: "hasAnswer"},
        {Name: "certainty"},
        {Name: "property"},
        {Name: "result"},
        {Name: "startPosition"},
        {Name: "endPosition"},
      }},
    }},
  }
  ask := client.GraphQL().AskArgBuilder().
    WithQuestion("Who is the king of the Netherlands?").
    WithProperties([]string{"summary"})
  ctx := context.Background()

  result, err := client.GraphQL().Get().
    WithClassName(className).
    WithFields(fields...).
    WithAsk(ask).
    WithLimit(1).
    Do(ctx)

  if err != nil {
    panic(err)
  }
  fmt.Printf("%v", result)
}
  package technology.semi.weaviate;

import technology.semi.weaviate.client.Config;
import technology.semi.weaviate.client.WeaviateClient;
import technology.semi.weaviate.client.base.Result;
import technology.semi.weaviate.client.v1.graphql.model.GraphQLResponse;
import technology.semi.weaviate.client.v1.graphql.query.argument.AskArgument;
import technology.semi.weaviate.client.v1.graphql.query.fields.Field;

public class App {
  public static void main(String[] args) {
    Config config = new Config("http", "localhost:8080");
    WeaviateClient client = new WeaviateClient(config);

    Field title = Field.builder().name("title").build();
    Field _additional = Field.builder()
      .name("_additional")
      .fields(new Field[]{
        Field.builder()
          .name("answer")
          .fields(new Field[]{
            Field.builder().name("hasAnswer").build(),
            Field.builder().name("certainty").build(),
            Field.builder().name("property").build(),
            Field.builder().name("result").build(),
            Field.builder().name("startPosition").build(),
            Field.builder().name("endPosition").build()
          }).build()
      }).build();

    AskArgument ask = AskArgument.builder()
      .question("Who is the king of the Netherlands?")
      .properties(new String[]{ "summary" })
      .build();

    Result<GraphQLResponse> result = client.graphQL().get()
      .withClassName("Article")
      .withFields(title, _additional)
      .withAsk(ask)
      .withLimit(1)
      .run();

    if (result.hasErrors()) {
      System.out.println(result.getError());
      return;
    }
    System.out.println(result.getResult());
  }
}
  $ echo '{ 
  "query": "{
    Get {
      Article(
        ask: {
          question: \"Who is the king of the Netherlands?\",
          properties: [\"summary\"]
        }, 
        limit: 1
      ) {
        title
        _additional {
          answer {
            hasAnswer
            certainty
            property
            result
            startPosition
            endPosition
          }
        }
      }
    }
  }
  "
}' | curl \
    -X POST \
    -H 'Content-Type: application/json' \
    -d @- \
    http://localhost:8080/v1/graphql

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

Additional information

The _additional{} property is extended with the answer and a certainty of the answer.

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.