Get by key

Retrieve entries by an exact vector-key match.

Every operation works on both Vector DB stores (you supply raw vectors) and AI stores (you supply text or images and Ahnlich AI generates the embeddings for you). Use the Vector DB / AI switch in the sample below.

Parameters

Parameter	Type	Description
store	string	Name of the store to read from.
keys	list of vectors	The exact vector keys to look up.
schema	string · optional	Schema to target. Defaults to public.

All requests accept an optional schema field. When omitted, the server uses the public schema.

Behavior

• Matches the stored entry whose key vector is exactly equal to the one supplied.
• Returns nothing for keys that aren't present — it does not do nearest-neighbour matching (use Similarity search for that).

Sample query

Database engine

Python

Python

import asyncio
from grpclib.client import Channel
from ahnlich_client_py.grpc import keyval
from ahnlich_client_py.grpc.services.db_service import DbServiceStub
from ahnlich_client_py.grpc.db import query as db_query
from ahnlich_client_py.grpc.db.server import Get

async def get_key():
  async with Channel(host="127.0.0.1", port=1369) as channel:
    client = DbServiceStub(channel)
    
    lookup_key = keyval.StoreKey(key=[1.0, 2.0, 3.0, 4.0])  # Your lookup vector
    
    response = await client.get_key(
      db_query.GetKey(
          store="my_store",
          schema="analytics",
          keys=[lookup_key]
      )
    )
    # response.entries contains matching (key, value) pairs
if __name__ == "__main__":
  asyncio.run(get_key())

Node.js

TypeScript

import { createDbClient } from "ahnlich-client-node";
import { GetKey } from "ahnlich-client-node/grpc/db/query_pb";
import { StoreKey } from "ahnlich-client-node/grpc/keyval_pb";

async function getKey() {
  const client = createDbClient("127.0.0.1:1369");

  const response = await client.getKey(
    new GetKey({
      store: "my_store",
      schema: "analytics",
      keys: [new StoreKey({ key: [1.0, 2.0, 3.0, 4.0] })],
    })
  );

  console.log(response.entries);

  // Iterate over results
  for (const entry of response.entries) {
    console.log(`Key: ${entry.key?.key}`);
    console.log(`Value: ${JSON.stringify(entry.value?.value)}`);
  }
}

getKey();

Go

Go

package main


import (
    "context"
    "fmt"
    "log"
    "time"


    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure"


    dbsvc   "github.com/deven96/ahnlich/sdk/ahnlich-client-go/grpc/services/db_service"
    dbquery "github.com/deven96/ahnlich/sdk/ahnlich-client-go/grpc/db/query"
    keyval  "github.com/deven96/ahnlich/sdk/ahnlich-client-go/grpc/keyval"
)


const ServerAddr = "127.0.0.1:1369"


// ExampleDBClient holds the gRPC connection, client, and context.
func stringPtr(value string) *string { return &value }


type ExampleDBClient struct {
    conn   *grpc.ClientConn
    client dbsvc.DBServiceClient
    ctx    context.Context
}


// NewDBClient connects to the Ahnlich DB server.
func NewDBClient(ctx context.Context) (*ExampleDBClient, error) {
    conn, err := grpc.NewClient(
        ServerAddr,
        grpc.WithTransportCredentials(insecure.NewCredentials()),
    )
    if err != nil {
        return nil, fmt.Errorf("failed to dial DB server %q: %w", ServerAddr, err)
    }
    client := dbsvc.NewDBServiceClient(conn)
    return &ExampleDBClient{conn: conn, client: client, ctx: ctx}, nil
}


// Close closes the gRPC connection.
func (c *ExampleDBClient) Close() error {
    return c.conn.Close()
}


// -------------------- GetKey --------------------
func (c *ExampleDBClient) exampleGetKey() error {
    resp, err := c.client.GetKey(c.ctx, &dbquery.GetKey{
        Store: "my_store",
        Schema: stringPtr("analytics"), // Optional: defaults to public when omitted
        Keys:  []*keyval.StoreKey{{Key: []float32{1, 2, 3, 4}}},
    })
    if err != nil {
        return err
    }
    fmt.Println("GetKey Results:")
    for _, entry := range resp.Entries {
        fmt.Println(" - Key:", entry.Key.Key, "Value:", entry.Value.Value)
    }
    return nil
}


// -------------------- Main --------------------
func main() {
    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
    defer cancel()


    client, err := NewDBClient(ctx)
    if err != nil {
        log.Fatalf("Failed to create DB client: %v", err)
    }
    defer client.Close()


    if err := client.exampleGetKey(); err != nil {
        log.Fatalf("GetKey failed: %v", err)
    }
}

Rust

Rust

use ahnlich_client_rs::db::DbClient;
use ahnlich_types::{
    db::query::GetKey,
    keyval::StoreKey,
};
use tokio;


#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // point to your DB server (default is 1369, adjust if needed)
    let addr = "http://127.0.0.1:1369";
    let client = DbClient::new(addr.to_string()).await?;


    // example: look up a key from store "my_store"
    let get_key_params = GetKey {
        store: "my_store".to_string(),
        schema: Some("analytics".to_string()),
        keys: vec![
            StoreKey {
                key: vec![1.2, 1.3, 1.4], // must match a previously Set key
            },
        ],
    };


    match client.get_key(get_key_params, None).await {
        Ok(result) => {
            println!("Fetched: {:#?}", result);
        }
        Err(e) => {
            eprintln!("Error fetching key: {:?}", e);
        }
    }


    Ok(())
}

CLI

$GETKEY ([1.0, 2.0, 3.0, 4.0]) IN my_store

AI proxy

Python

Python

import asyncio
from grpclib.client import Channel
from ahnlich_client_py.grpc.services.ai_service import AiServiceStub
from ahnlich_client_py.grpc.ai import query as ai_query
from ahnlich_client_py.grpc import keyval


async def get_key():
  async with Channel(host="127.0.0.1", port=1370) as channel:
      client = AiServiceStub(channel)
      
      response = await client.get_key(
          ai_query.GetKey(
              store="my_store",
              schema="analytics",
              keys=[
                  keyval.StoreInput(raw_string="Adidas Yeezy"),
                  keyval.StoreInput(raw_string="Nike Air Jordans"),
              ]
          )
      )
      
      # Response contains entries for each found key
      for entry in response.entries:
          print(f"Key: {entry.key}")
          print(f"Value: {entry.value}")


if __name__ == "__main__":
  asyncio.run(get_key())

Node.js

TypeScript

import { createAiClient } from "ahnlich-client-node";
import { GetKey } from "ahnlich-client-node/grpc/ai/query_pb";
import { StoreInput } from "ahnlich-client-node/grpc/keyval_pb";

async function getKey() {
  const client = createAiClient("127.0.0.1:1370");

  // Create the input to look up (using oneof discriminated union)
  const storeInput = new StoreInput({
    value: {
      case: "rawString",
      value: "Your search text"
    }
  });

  const response = await client.getKey(
    new GetKey({
      store: "my_store",
      schema: "analytics",
      keys: [storeInput]
    })
  );

  // response.entries contains matching (key, value) pairs
  for (const entry of response.entries) {
    console.log("Found entry:", entry);
  }
}

getKey();

Go

Go

package main


import (
  "context"
  "fmt"
  "log"
  "time"


  "google.golang.org/grpc"
  "google.golang.org/grpc/credentials/insecure"


  aiquery  "github.com/deven96/ahnlich/sdk/ahnlich-client-go/grpc/ai/query"
  aisvc    "github.com/deven96/ahnlich/sdk/ahnlich-client-go/grpc/services/ai_service"
  keyval   "github.com/deven96/ahnlich/sdk/ahnlich-client-go/grpc/keyval"
)


const AIAddr = "127.0.0.1:1370"


func stringPtr(value string) *string { return &value }


type ExampleAIClient struct {
  conn   *grpc.ClientConn
  client aisvc.AIServiceClient
  ctx    context.Context
}


func NewAIClient(ctx context.Context) (*ExampleAIClient, error) {
  conn, err := grpc.DialContext(ctx, AIAddr, grpc.WithTransportCredentials(insecure.NewCredentials()), grpc.WithBlock())
  if err != nil {
      return nil, fmt.Errorf("failed to dial AI server %q: %w", AIAddr, err)
  }
  client := aisvc.NewAIServiceClient(conn)
  return &ExampleAIClient{conn: conn, client: client, ctx: ctx}, nil
}


func (c *ExampleAIClient) Close() error {
  return c.conn.Close()
}


// ---- GetKey Example ----
func (c *ExampleAIClient) exampleGetKey() error {
  resp, err := c.client.GetKey(c.ctx, &aiquery.GetKey{
      Store: "ai_store01",
      Schema: stringPtr("analytics"), // Optional: defaults to public when omitted
      Keys: []*keyval.StoreInput{
          {Value: &keyval.StoreInput_RawString{RawString: "Adidas Yeezy"}},
          {Value: &keyval.StoreInput_RawString{RawString: "Nike Air Jordans"}},
      },
  })
  if err != nil {
      return err
  }

  fmt.Println("GetKey Results:")
  for _, entry := range resp.Entries {
      fmt.Printf("  Key: %v\n", entry.Key)
      fmt.Printf("  Value: %v\n", entry.Value)
  }
  return nil
}


func main() {
  ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
  defer cancel()


  client, err := NewAIClient(ctx)
  if err != nil {
      log.Fatalf("Failed to create AI client: %v", err)
  }
  defer client.Close()


  if err := client.exampleGetKey(); err != nil {
      log.Fatalf("GetKey failed: %v", err)
  }
}

Rust

Rust

use ahnlich_client_rs::ai::AiClient;
use ahnlich_client_rs::error::AhnlichError;
use ahnlich_types::ai::query::GetKey;
use ahnlich_types::keyval::store_input::Value;
use ahnlich_types::keyval::StoreInput;


#[tokio::main]
async fn main() -> Result<(), AhnlichError> {
    let addr = "127.0.0.1:1370";
    let client = AiClient::new(addr.to_string()).await?;


    let keys = vec![
        StoreInput { value: Some(Value::RawString("Adidas Yeezy".to_string())) },
        StoreInput { value: Some(Value::RawString("Nike Air Jordans".to_string())) },
    ];


    let params = GetKey {
        store: "Main0".to_string(),
        schema: Some("analytics".to_string()),
        keys, // directly pass the Vec
    };


    let result = client.get_key(params, None).await?;


    for entry in result.entries {
        if let Some(k) = entry.key {
            println!("Key retrieved: {:?}", k.value);
        }
    }


    Ok(())
}

CLI

$GETKEY ([This is a sentence]) IN my_store

Response

The matching entries (vector + metadata). Empty if no key matches.

Related

• Similarity search
• Get by predicate