API: Redesign of Query & Retrieval API

[ppanopticon]

Description

The vitrivr-engine query API should be finalized and stabilized. In its current state, it has several shortcomings, that must be addressed in order to prepare it for future use and use-cases.

The goal of this issue is to do exactly that. We plan to do this along the following dimensions:

• Definition: The existing API definitions, and the objects used to represent them, must be revisited with respect to completeness, expressiveness and ease-of-use.
• Categorization: Common Operators used in these APIs should be defined and categorized.
• Implementation: Missing implementation(s) of Operators should be added.

Advantages & Shortcomings

The current API implementation has a singular advantage, which should be maintained: It is quite straightforward and easy to use. However, it comes with several shortcomings:

• It's more like a minimal working example designed with a particular use-case in mind.
• It's incomplete in terms of supported Operators.
• It's code is poorly documented
• The resulting Open API endpoints are not usable for everyone (e.g., C# @Spiess can maybe elaborate).
• Implementations are not part of vitrivr-engine-core
• The API design differs from the ingest API, which, ideally, should be identical.

Notes on Scope

The issues is about the definition and implementations of the API and not the general, operator-based model of data processing. Also the vitrivr-engine data model is out-of-scope for this issue.

[ppanopticon]

Discussion on the query API are open. Please add your suggestion, design-goals, issues etc.

[Spiess]

I have had a very brief first look on the current main branch and there again appear to be structural errors with the OpenAPI specifications that prevent a query client to be built from this.

The errors are caused by duplicate items in the required sections on lines 303, 1007, 1097, and 1149.

Please let me know if I should create separate issue for this.

[ppanopticon]

I don't think this warrants a separate issue. We simply have to make sure that the OpenAPI specification is correct.

I have checked the issues you mentioned and the underlying Problem is that we expose native Java classes through our own API objects (e.g., Rectangle2D, BufferedImage, ColorModel).

[ppanopticon]

Summary of Meeting:

• Retain basic architecture of operators
• Extend input types
• Add basic case of retrieval based on RetrievableIds and DescriptorIds
• Expose all inputs in QueryContext

Inputs:

• Content types (Text, Image, Audio, Video ...)
• Value types (Float, Double, String, Int, Long)
• Array of Value types
• Map of Value types (for building Descriptors)
• DescriptorsIds
• RetrievableIds
• Query-objects (Proximity, Boolean, Fulltext)