Querying the Worker

Selecting an Interface

Orter provides several interfaces for querying data in collections assigned to a worker instance. To help you choose the most suitable interface, consider the following recommendations:

For ease of use, flexibility, or web applications, we recommend:

• REST Interface
  The REST interface is easy to integrate. However, if you require high throughput or low latency, consider another interface. Each request to the worker agent incurs overhead, resulting in higher latency and lower maximum throughput.
• WebSocket Interface
  The WebSocket interface requires slightly more integration effort, but offers significantly better performance than REST. A single WebSocket connection can be used to submit multiple queries with minimal overhead.

For high performance and network access, we recommend:

• TCP Interface
  TCP offers low overhead, resulting in low latency and high throughput. Using the TCP interface requires more integration work, especially if you are less familiar with TCP sockets.
• UDP Interface
  UDP provides extremely low overhead, resulting in very low latency and very high throughput. Integration effort is higher for UDP sockets. Note: UDP does not guarantee delivery of queries and responses between client and worker. If reliability is important, use the TCP Interface.

For high performance and local access:

• UNIX Socket Interface
  This is the best performing interface in terms of throughput and latency, but requires significant integration effort. It is best used as a sidecar container.

Authentication

Request Flow

All interfaces except REST operate in a highly asynchronous manner. As a result, not every request will receive a corresponding Response from the Orter worker. By default, the Orter worker does not return empty responses. If you require a response for every request, you can enable this behavior by setting the always_return field in the Query. However, enabling this option can significantly degrade performance in high-throughput scenarios due to increased network traffic between the worker and the client.

To correlate a Response with its originating Query, you can assign a unique request_id to each Query. The corresponding Response will include the same request_id value.

Interfaces

REST

The worker exposes a REST interface on port 8082. Assuming you have a collection loaded on the worker agent, you can query the worker as follows:

export COLLECTION_ID=93a278aa-87c4-4ee0-8dc3-c7a7fce77806
export LATITUDE=43
export LONGITUDE=11
export SEARCH_RADIUS_M=300
 
curl localhost:8082/collection/$COLLECTION_ID?lat=$LATITUDE&long=$LONGITUDE&radius=$SEARCH_RADIUS_M

WebSocket

TCP

The worker client provides a TCP interface on port 6969. Refer to the Query schema and Response schema for request and response formats. All queries must be newline separated; append a \n at the end of your query.

echo "{\"lat\": 43, \"lon\": 11, \"radius\": 300}\n" | nc 127.0.0.1 6969

UDP

The worker client provides a UDP interface on port 6666. Refer to the Query schema and Response schema for request and response formats. All queries must be newline separated; append a \n at the end of your query.

echo "{\"lat\": 43, \"lon\": 11, \"radius\": 300}\n" | nc -u 127.0.0.1 6666

UNIX Socket

echo "{\"lat\": 43, \"lon\": 11, \"radius\": 300}\n" | socat - UNIX-CONNECT:/var/tmp/orter.sock

gRPC

Schemas

Query

pub struct Query {
    pub lon: f64,
    pub lat: f64,
    /// Radius in meters
    pub radius: f64,
    /// If None, query all collections
    pub collections: Option<Vec<Uuid>>,
    /// Optional request ID for tracking
    pub request_id: Option<Uuid>,
    /// If Some(true), always return a response, even if empty 
    /// Enabling this flag can degrade performance significantly 
    pub always_return: Option<bool>,
}

Response

pub struct Response {
    pub response: Vec<serde_json::Value>,
    pub request_id: Option<Uuid>,
}