Qdrant Client for HeroLib

This is a V client for Qdrant, a high-performance vector database and similarity search engine.

Features

• Collection management (create, list, delete, get info)
• Points management (upsert, delete, search, get)
• Service information and health checks
• Support for filters, payload management, and vector operations

Usage

Initialize Client

// Create a new Qdrant client
import freeflowuniverse.herolib.clients.qdrant

mut client := qdrant.get()!

// Or create with custom configuration
mut custom_client := qdrant.QDrantClient{
    name: 'custom',
    url: 'http://localhost:6333',
    secret: 'your_api_key' // Optional
}
qdrant.set(custom_client)!

Collection Management

// Create a collection
vectors_config := qdrant.VectorsConfig{
    size: 128,
    distance: .cosine
}

client.create_collection(
    collection_name: 'my_collection',
    vectors: vectors_config
)!

// List all collections
collections := client.list_collections()!

// Get collection info
collection_info := client.get_collection(
    collection_name: 'my_collection'
)!

// Delete a collection
client.delete_collection(
    collection_name: 'my_collection'
)!

Points Management

// Upsert points
points := [
    qdrant.PointStruct{
        id: '1',
        vector: [f32(0.1), 0.2, 0.3, 0.4],
        payload: {
            'color': 'red',
            'category': 'furniture'
        }
    },
    qdrant.PointStruct{
        id: '2',
        vector: [f32(0.2), 0.3, 0.4, 0.5],
        payload: {
            'color': 'blue',
            'category': 'electronics'
        }
    }
]

client.upsert_points(
    collection_name: 'my_collection',
    points: points,
    wait: true
)!

// Search for points
search_result := client.search(
    collection_name: 'my_collection',
    vector: [f32(0.1), 0.2, 0.3, 0.4],
    limit: 10
)!

// Get a point by ID
point := client.get_point(
    collection_name: 'my_collection',
    id: '1'
)!

// Delete points
client.delete_points(
    collection_name: 'my_collection',
    points_selector: qdrant.PointsSelector{
        points: ['1', '2']
    },
    wait: true
)!

Service Information

// Get service info
service_info := client.get_service_info()!

// Check health
is_healthy := client.health_check()!

Advanced Usage

Filtering

// Create a filter
filter := qdrant.Filter{
    must: [
        qdrant.FieldCondition{
            key: 'color',
            match: 'red'
        },
        qdrant.FieldCondition{
            key: 'price',
            range: qdrant.Range{
                gte: 10.0,
                lt: 100.0
            }
        }
    ]
}

// Search with filter
search_result := client.search(
    collection_name: 'my_collection',
    vector: [f32(0.1), 0.2, 0.3, 0.4],
    filter: filter,
    limit: 10
)!

Example HeroScript

!!qdrant.configure
    name: 'default'
    secret: 'your_api_key'
    url: 'http://localhost:6333'

Installation

Qdrant server can be installed using the provided installer script:

~/code/github/freeflowuniverse/herolib/examples/installers/db/qdrant.vsh

This will install and start a Qdrant server locally.

fn delete(args_ ArgsGet) !

fn exists(args_ ArgsGet) !bool

does the config exists?

fn get(args_ ArgsGet) !&QDrantClient

fn heroscript_dumps(obj QDrantClient) !string

///////////NORMALLY NO NEED TO TOUCH

fn heroscript_loads(heroscript string) !QDrantClient

fn play(args_ PlayArgs) !

fn set(o QDrantClient) !

register the config for the future

fn switch(name string)

switch instance to be used for qdrant

struct ArgsGet {
pub mut:
	name string
}

///////FACTORY

struct ClearPayloadParams {
pub mut:
	collection_name string    @[json: 'collection_name'; required] // Name of the collection
	points          ?[]string @[json: 'points']                    // List of point IDs to clear payload for
	filter          ?Filter   @[json: 'filter']                    // Filter condition to select points
	wait            ?bool     @[json: 'wait']                      // Whether to wait until the changes have been applied
}

Parameters for clearing payload

struct CollectionConfig {
pub mut:
	params              CollectionParams    // Collection parameters
	hnsw_config         HNSWConfig          // HNSW configuration
	optimizer_config    OptimizerConfig     // Optimizer configuration
	wal_config          WALConfig           // WAL configuration
	quantization_config ?QuantizationConfig // Optional quantization configuration, Nullable field
	strict_mode_config  StrictModeConfig    // Strict mode configuration
}

Configuration of the collection

struct CollectionExistenceParams {
pub mut:
	collection_name string @[json: 'name'; required] // Name of the collection
}

Check collection existence

struct CollectionExistenceResponse {
pub mut:
	exists bool // Collection existence
}

Check collection existence

struct CollectionNameParams {
pub mut:
	collection_name string @[json: 'name'; required] // Name of the collection
}

Get a collection arguments

struct CollectionParams {
pub mut:
	vectors                  VectorConfig // Vector configuration
	shard_number             int          // Number of shards
	replication_factor       int          // Replication factor
	write_consistency_factor int          // Write consistency factor
	on_disk_payload          bool         // On-disk payload
}

Parameters of the collection

struct CountPointsParams {
pub mut:
	collection_name string  @[json: 'collection_name'; required] // Name of the collection
	filter          ?Filter @[json: 'filter']                    // Filter conditions
	exact           ?bool   @[json: 'exact']                     // Whether to calculate exact count
}

Parameters for counting points

struct CountResponse {
pub mut:
	count int @[json: 'count'] // Number of points matching the filter
}

Response structure for count operation

struct CreateCollectionParams {
pub mut:
	collection_name string @[required] // Name of the collection
	size            int    @[required] // Size of the vectors
	distance        string @[required] // Distance function
}

Create a collection arguments

struct CreateIndexParams {
pub mut:
	collection_name string      @[json: 'collection_name'; required] // Name of the collection
	field_name      string      @[json: 'field_name'; required]      // Name of the field to create index for
	field_schema    FieldSchema @[json: 'field_schema'; required]    // Schema of the field
	wait            ?bool       @[json: 'wait']                      // Whether to wait until the changes have been applied
}

Parameters for creating an index

struct DefaultConfigArgs {
	instance string = 'default'
}

helpers

struct DeleteCollectionParams {
pub mut:
	collection_name string @[required] // Name of the collection
}

Delete a collection arguments

struct DeleteIndexParams {
pub mut:
	collection_name string @[json: 'collection_name'; required] // Name of the collection
	field_name      string @[json: 'field_name'; required]      // Name of the field to delete index for
	wait            ?bool  @[json: 'wait']                      // Whether to wait until the changes have been applied
}

Parameters for deleting an index

struct DeletePayloadParams {
pub mut:
	collection_name string    @[json: 'collection_name'; required] // Name of the collection
	keys            []string  @[json: 'keys'; required]            // List of payload keys to delete
	points          ?[]string @[json: 'points']                    // List of point IDs to delete payload from
	filter          ?Filter   @[json: 'filter']                    // Filter condition to select points
	wait            ?bool     @[json: 'wait']                      // Whether to wait until the changes have been applied
}

Parameters for deleting payload

struct DeletePointsParams {
pub mut:
	collection_name string         @[json: 'collection_name'; required] // Name of the collection
	points_selector PointsSelector @[json: 'points_selector'; required] // Points selector
	wait            ?bool          @[json: 'wait']                      // Whether to wait until the changes have been applied
}

Parameters for deleting points

struct DeletePointsResponse {
pub mut:
	status       string @[json: 'status']
	operation_id int    @[json: 'operation_id']
}

Response structure for delete points operation

struct FieldCondition {
pub mut:
	key           string  @[json: 'key'; required] // Field name to filter by
	match_        ?string @[json: 'match']         // Exact match value (string)
	match_integer ?int    @[json: 'match']         // Exact match value (integer)
	match_float   ?f64    @[json: 'match']         // Exact match value (float)
	match_bool    ?bool   @[json: 'match']         // Exact match value (boolean)
	range         ?Range  @[json: 'range']         // Range condition
}

Filter condition for field matching

struct FieldSchema {
pub mut:
	field_type string @[json: 'type'; required] // Type of the field (keyword, integer, float, geo)
}

Field schema for index

struct Filter {
pub mut:
	must     ?[]FieldCondition @[json: 'must']     // All conditions must match
	must_not ?[]FieldCondition @[json: 'must_not'] // None of the conditions should match
	should   ?[]FieldCondition @[json: 'should']   // At least one condition should match
}

Filter structure for search operations

struct GetCollectionParams {
pub mut:
	collection_name string @[required] // Name of the collection
}

Get a collection arguments

struct GetCollectionResponse {
pub mut:
	status                string            // Status
	optimizer_status      string            // Optimizer status
	indexed_vectors_count int               // Indexed vectors count
	points_count          int               // Points count
	segments_count        int               // Segments count
	config                CollectionConfig  // Collection configuration
	payload_schema        map[string]string // Payload schema
}

Result field containing detailed information about the collection

struct GetPointParams {
pub mut:
	collection_name string @[json: 'collection_name'; required] // Name of the collection
	id              string @[json: 'id'; required]              // ID of the point to retrieve
	with_payload    ?bool // Whether to include payload in the response
	with_vector     ?bool // Whether to include vector in the response
}

Parameters for getting a point by ID

struct GetPointResponse {
pub mut:
	id      string            // Point ID
	payload map[string]string // Payload key-value pairs
	vector  ?[]f64            // Vector data (optional)
}

Response structure for the get point operation

struct HNSWConfig {
pub mut:
	m                    int  // Number of neighbors
	ef_construct         int  // Number of neighbors
	full_scan_threshold  int  // Full scan threshold
	max_indexing_threads int  // Maximum indexing threads
	on_disk              bool // On-disk storage
}

HNSW (Hierarchical Navigable Small World) configuration

struct HealthCheckResponse {
pub mut:
	title   string // Title of the health check
	status  string // Status of the health check
	version string // Version of the Qdrant server
}

Health check response

struct IndexOperationResponse {
pub mut:
	status       string @[json: 'status']
	operation_id int    @[json: 'operation_id']
}

Response structure for index operations

struct ListCollectionParams {
	collections []CollectionNameParams // List of collection names
}

Get a collection arguments

struct OptimizerConfig {
pub mut:
	deleted_threshold        f64  // Deleted threshold
	vacuum_min_vector_number int  // Minimum vector number
	default_segment_number   int  // Default segment number
	max_segment_size         ?int // Nullable field
	memmap_threshold         ?int // Nullable field
	indexing_threshold       int  // Indexing threshold
	flush_interval_sec       int  // Flush interval
	max_optimization_threads ?int // Nullable field
}

Optimizer configuration

struct PayloadOperationResponse {
pub mut:
	status       string @[json: 'status']
	operation_id int    @[json: 'operation_id']
}

Response structure for payload operations

struct PlayArgs {
pub mut:
	heroscript string // if filled in then plbook will be made out of it
	plbook     ?playbook.PlayBook
	reset      bool
}

struct Point {
pub mut:
	id      string = rand.uuid_v4()            @[json: 'id'; required]            // Point ID (can be string or integer, serialized as string)
	payload map[string]string @[json: 'payload']          // Payload key-value pairs (optional)
	vector  []f64             @[json: 'vector'; required] // Vector data for the point
}

Represents a single point to be upserted.

struct PointStruct {
pub mut:
	id      string             @[json: 'id']      // Point ID
	payload ?map[string]string @[json: 'payload'] // Payload key-value pairs (optional)
	vector  ?[]f64             @[json: 'vector']  // Vector data (optional)
}

Point structure for scroll results

struct PointsSelector {
pub mut:
	points ?[]string @[json: 'points'] // List of point IDs to delete
	filter ?Filter   @[json: 'filter'] // Filter condition to select points for deletion
}

Points selector for delete operation

struct QDrantClient {
pub mut:
	name   string = 'default'
	secret string
	url    string = 'http://localhost:6333/'
}

THIS THE THE SOURCE OF THE INFORMATION OF THIS FILE, HERE WE HAVE THE CONFIG OBJECT CONFIGURED AND MODELLED

fn (mut self QDrantClient) clear_payload(params ClearPayloadParams) !QDrantResponse[PayloadOperationResponse]

Clear payload for points

fn (mut self QDrantClient) count_points(params CountPointsParams) !QDrantResponse[CountResponse]

Count points in a collection

fn (mut self QDrantClient) create_collection(params CreateCollectionParams) !QDrantResponse[bool]

Create a collection

fn (mut self QDrantClient) create_index(params CreateIndexParams) !QDrantResponse[IndexOperationResponse]

Create an index for a field in a collection

fn (mut self QDrantClient) delete_collection(params DeleteCollectionParams) !QDrantResponse[bool]

Delete a collection

fn (mut self QDrantClient) delete_index(params DeleteIndexParams) !QDrantResponse[IndexOperationResponse]

Delete an index for a field in a collection

fn (mut self QDrantClient) delete_payload(params DeletePayloadParams) !QDrantResponse[PayloadOperationResponse]

Delete payload for points

fn (mut self QDrantClient) delete_points(params DeletePointsParams) !QDrantResponse[DeletePointsResponse]

Delete points from a collection

fn (mut self QDrantClient) get_collection(params GetCollectionParams) !QDrantResponse[GetCollectionResponse]

Get a collection

fn (mut self QDrantClient) get_point(params GetPointParams) !QDrantResponse[GetPointResponse]

Get a point by ID

fn (mut self QDrantClient) get_service_info() !QDrantResponse[ServiceInfo]

Get service information

fn (mut self QDrantClient) health_check() !bool

Check health of the Qdrant server

fn (mut self QDrantClient) is_collection_exists(params CollectionExistenceParams) !QDrantResponse[CollectionExistenceResponse]

Check collection existence

fn (mut self QDrantClient) list_collections() !QDrantResponse[ListCollectionParams]

List a collection

fn (mut self QDrantClient) retrieve_points(params RetrievePointsParams) !QDrantResponse[RetrievePointsResponse]

Retrieves all details from multiple points.

fn (mut self QDrantClient) scroll_points(params ScrollPointsParams) !QDrantResponse[ScrollResponse]

Scroll through points with pagination

fn (mut self QDrantClient) search(params SearchParams) !QDrantResponse[SearchResponse]

Search for points based on vector similarity

fn (mut self QDrantClient) set_payload(params SetPayloadParams) !QDrantResponse[PayloadOperationResponse]

Set payload for points

fn (mut self QDrantClient) upsert_points(params UpsertPointsParams) !QDrantResponse[UpsertPointsResponse]

Upserts points into a Qdrant collection. Performs insert + update actions on specified points. Any point with an existing {id} will be overwritten.

struct QDrantError {
pub mut:
	error string // Error message
}

Qdrant error response

struct QDrantErrorResponse {
pub mut:
	status QDrantError // Response status
	time   f64         // Response time
}

struct QDrantResponse[T] {
pub mut:
	usage  QDrantUsage // Usage information
	result T           // The result
	status string      // Response status
	time   f64         // Response time
}

Top-level response structure

struct QDrantUsage {
pub mut:
	cpu      int // CPU usage
	io_read  int // I/O read usage
	io_write int // I/O write usage
}

QDrant usage

struct QuantizationConfig {
pub mut:
	scalar ?ScalarQuantization // Nullable field
}

Quantization configuration (nullable)

struct Range {
pub mut:
	lt  ?f64 @[json: 'lt']  // Less than
	gt  ?f64 @[json: 'gt']  // Greater than
	gte ?f64 @[json: 'gte'] // Greater than or equal
	lte ?f64 @[json: 'lte'] // Less than or equal
}

Range condition for numeric fields

struct RetrievePointsParams {
pub mut:
	ids             []int  @[json: 'ids'; required]             // Look for points with ids
	collection_name string @[json: 'collection_name'; required] // Name of the collection
	shard_key       ?string // Specify in which shards to look for the points, if not specified - look in all shards
	with_payload    ?bool   // Select which payload to return with the response. Default is true.
	with_vectors    ?bool   // Options for specifying which vectors to include into response. Default is false.
}

Retrieves all details from multiple points.

struct RetrievePointsResponse {
pub mut:
	id          int               // Type, used for specifying point ID in user interface
	payload     map[string]string // Payload - values assigned to the point
	vector      []f64             // Vector of the point
	shard_id    string            // Shard name
	order_value f64               // Order value
}

struct ScalarQuantization {
pub mut:
	typ string @[json: 'type'] // Quantization type
}

Scalar quantization configuration

struct ScoredPoint {
pub mut:
	id      string             @[json: 'id']      // Point ID
	payload ?map[string]string @[json: 'payload'] // Payload key-value pairs (optional)
	vector  ?[]f64             @[json: 'vector']  // Vector data (optional)
	score   f64                @[json: 'score']   // Similarity score
}

Scored point in search results

struct ScrollPointsParams {
pub mut:
	collection_name string  @[json: 'collection_name'; required] // Name of the collection
	filter          ?Filter @[json: 'filter']                    // Filter conditions
	limit           int = 10     @[json: 'limit']                                 // Max number of results
	offset          ?string @[json: 'offset']                    // Offset from which to continue scrolling
	with_payload    ?bool   @[json: 'with_payload']              // Whether to include payload in the response
	with_vector     ?bool   @[json: 'with_vector']               // Whether to include vectors in the response
}

Parameters for scrolling through points

struct ScrollResponse {
pub mut:
	points           []PointStruct @[json: 'points']           // List of points
	next_page_offset ?string       @[json: 'next_page_offset'] // Offset for the next page
}

Response structure for scroll operation

struct SearchParams {
pub mut:
	collection_name string  @[json: 'collection_name'; required] // Name of the collection
	vector          []f64   @[json: 'vector'; required]          // Vector to search for
	filter          ?Filter @[json: 'filter']                    // Filter conditions
	limit           int = 10     @[json: 'limit']                                 // Max number of results
	offset          ?int    @[json: 'offset']                    // Offset of the first result to return
	with_payload    ?bool   @[json: 'with_payload']              // Whether to include payload in the response
	with_vector     ?bool   @[json: 'with_vector']               // Whether to include vectors in the response
	score_threshold ?f64    @[json: 'score_threshold']           // Minimal score threshold
}

Parameters for searching points

struct SearchResponse {
pub mut:
	points []ScoredPoint @[json: 'points'] // List of scored points
}

Response structure for search operation

struct ServiceInfo {
pub mut:
	version string  // Version of the Qdrant server
	commit  ?string // Git commit hash
}

Service information

struct SetPayloadParams {
pub mut:
	collection_name string            @[json: 'collection_name'; required] // Name of the collection
	payload         map[string]string @[json: 'payload'; required]         // Payload to set
	points          ?[]string         @[json: 'points']                    // List of point IDs to set payload for
	filter          ?Filter           @[json: 'filter']                    // Filter condition to select points
	wait            ?bool             @[json: 'wait']                      // Whether to wait until the changes have been applied
}

Parameters for setting payload

struct StrictModeConfig {
pub mut:
	enabled bool // Enabled
}

Strict mode configuration

struct UpsertPointsParams {
pub mut:
	collection_name string  @[json: 'collection_name'; required] // Name of the collection
	points          []Point @[json: 'points'; required]          // List of points to upsert
	shard_key       ?string // Optional shard key for sharding
	wait            ?bool   // Whether to wait until the changes have been applied
}

Parameters for upserting points into a Qdrant collection.

struct UpsertPointsResponse {
pub mut:
	status       string @[json: 'status']
	operation_id int    @[json: 'operation_id']
}

Response structure for the upsert points operation.

struct VectorConfig {
pub mut:
	size     int    // Size of the vectors
	distance string // Distance function
}

Vector configuration

struct WALConfig {
pub mut:
	wal_capacity_mb    int // WAL capacity in megabytes
	wal_segments_ahead int // WAL segments ahead
}

Write-Ahead Log (WAL) configuration