Low-level gRPC API

This section describes the low-level gRPC API that you can use from any other language or any other server/service proxy.

EuclidesDB implements the following gRPC calls:

service Similar {
    rpc Shutdown (ShutdownRequest) returns (ShutdownReply) {}
    rpc FindSimilarImage (FindSimilarImageRequest) returns (FindSimilarImageReply) {}
    rpc FindSimilarImageById (FindSimilarImageByIdRequest) returns (FindSimilarImageReply) {}
    rpc AddImage (AddImageRequest) returns (AddImageReply) {}
    rpc RemoveImage (RemoveImageRequest) returns (RemoveImageReply) {}
}

Each one of these RPC calls are described in the next sections. Errors are returned as gRPC errors with a CANCELED status.

See also

See the gRPC documentation for more information. If you’re not familiar with protobuf syntax, please take a look on these tutorials.

AddImage – add a new image item into the database

The prototype of the AddImage call is the following:

rpc AddImage (AddImageRequest) returns (AddImageReply) {}

This RPC call will accept a AddImageRequest request object as input and it will return a AddImageReply as result. The definition of these objects are described below:

message AddImageRequest {
    int32 image_id = 1;
    bytes image_data = 2;
    bytes image_metadata = 3;
    repeated string models = 4;
}

message AddImageReply {
    repeated ItemVectors vectors = 1;
}

These definitions are quite simple and the field names describe the meaning of each field. The ItemVectors is described below:

message ItemVectors {
    string model = 1;
    repeated float predictions = 2;
    repeated float features = 3;
}

Which is the predictions and features for each model space.

RemoveImage – removes an image item from the database

The prototype of the RemoveImage call is the following:

rpc RemoveImage (RemoveImageRequest) returns (RemoveImageReply) {}

This RPC call will accept a RemoveImageRequest request object as input and it will return a RemoveImageReply as result. The definition of these objects are described below:

message RemoveImageRequest {
    int32 image_id = 1;
}

message RemoveImageReply {
    int32 image_id = 1;
}

This call will accept a image_id as input and it will answer with the same field.

FindSimilarImageById – find similar items to an item existing in the database

The prototype of the FindSimilarImageById call is the following:

rpc FindSimilarImageById (FindSimilarImageByIdRequest) returns (FindSimilarImageReply) {}

This RPC call will accept a FindSimilarImageByIdRequest request object as input and it will return a FindSimilarImageReply as result. The definition of these objects are described below:

message FindSimilarImageByIdRequest {
    int32 top_k = 1;
    int32 image_id = 2;
    repeated string models = 3;
}

message FindSimilarImageReply {
    repeated SearchResults results = 1;
}

This RPC call will accept a top_k that is the number of similar items you want EuclidesDB to return, the item id and the model spaces you want to search. The definition of the SearchResults is described below:

message SearchResults {
    repeated int32 top_k_ids = 1;
    repeated float distances = 2;
    string model = 3;
}

Which is basically the ids of the closest items, their distances and the model where these ids were found.

FindSimilarImage – find similar items to a new item

The prototype of the FindSimilarImage call is the following:

rpc FindSimilarImage (FindSimilarImageRequest) returns (FindSimilarImageReply) {}

This RPC call will accept a FindSimilarImageRequest request object as input and it will return a FindSimilarImageReply as result. The definition of these objects are described below:

message FindSimilarImageRequest {
    int32 top_k = 1;
    bytes image_data = 2;
    repeated string models = 3;
}

message FindSimilarImageReply {
    repeated SearchResults results = 1;
}

This RPC call will accept a top_k that is the number of similar items you want EuclidesDB to return, the image data and the model spaces you want to search. The definition of the SearchResults is the same described in the FindSimilarImageById call.

Shutdown – request a shutdown command (shutdown/refresh indexes)

The prototype of the Shutdown call is the following:

rpc Shutdown (ShutdownRequest) returns (ShutdownReply) {}

This RPC call will accept a ShutdownRequest request object as input and it will return a ShutdownReply as result. The definition of these objects are described below:

message ShutdownRequest {
    int32 shutdown_type = 1;
}

message ShutdownReply {
    bool shutdown = 1;
}

The shutdown_type can be one of the following:

• 0 - a regular database shutdown, it will shutdown EuclidesDB immediately after waiting for all the calls to complete gracefully;
• 1 - a request for EuclidesDB to refresh its indexes. This must be called after adding items into the database (at the end after adding all items). The semantics of this action is that EuclidesDB will gracefully wait for all requests to finish, it will then do a momentary stop while refreshing its memory indexes (this depend on the amount of data in the database and search engine selected) and then it will start to accept requests again. Any call during the refreshing process will not be processed.

This call will return true if the request was accepted or false otherwise. Currently, there is no false return from this call, because the call is always accepted.