use qql_core::error::QqlError;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum EdgeUnsupported {
GroupBy,
ShardRouting,
CollectionSharding,
ShardKeyDdl,
AlterCollection,
CollectionParams,
Acorn,
Timeout,
Consistency,
RecommendAverageVector,
PointReferenceQuery,
Route { path_hint: &'static str },
}
impl EdgeUnsupported {
pub fn code(self) -> &'static str {
match self {
Self::GroupBy => "QQL-EDGE-UNSUPPORTED-GROUP-BY",
Self::ShardRouting | Self::CollectionSharding => "QQL-EDGE-UNSUPPORTED-SHARD",
Self::ShardKeyDdl => "QQL-EDGE-UNSUPPORTED-SHARD-KEY",
Self::AlterCollection => "QQL-EDGE-UNSUPPORTED-ALTER",
Self::CollectionParams => "QQL-EDGE-UNSUPPORTED-COLLECTION-PARAMS",
Self::Acorn => "QQL-EDGE-UNSUPPORTED-ACORN",
Self::Timeout => "QQL-EDGE-UNSUPPORTED-TIMEOUT",
Self::Consistency => "QQL-EDGE-UNSUPPORTED-CONSISTENCY",
Self::RecommendAverageVector => "QQL-EDGE-UNSUPPORTED-RECOMMEND-STRATEGY",
Self::PointReferenceQuery => "QQL-EDGE-UNSUPPORTED-POINT-REF",
Self::Route { .. } => "QQL-EDGE-UNSUPPORTED-ROUTE",
}
}
pub fn feature(self) -> &'static str {
match self {
Self::GroupBy => "GROUP BY / query groups",
Self::ShardRouting => "SHARD routing",
Self::CollectionSharding => {
"collection sharding (shard_number / sharding_method / shard_keys)"
}
Self::ShardKeyDdl => "CREATE/DROP SHARD KEY",
Self::AlterCollection => "ALTER COLLECTION",
Self::CollectionParams => "collection WITH PARAMS (replication, etc.)",
Self::Acorn => "PARAMS (acorn = …)",
Self::Timeout => "PARAMS (timeout = …)",
Self::Consistency => "PARAMS (consistency = …)",
Self::RecommendAverageVector => "RECOMMEND STRATEGY average_vector",
Self::PointReferenceQuery => "point-id query inputs without embedded vectors",
Self::Route { path_hint } => path_hint,
}
}
pub fn why(self) -> &'static str {
match self {
Self::GroupBy => "qdrant-edge has no /points/query/groups endpoint",
Self::ShardRouting | Self::CollectionSharding | Self::ShardKeyDdl => {
"qql-edge is a single-node process with no custom shard keys"
}
Self::AlterCollection => "qql-edge does not support collection mutation after create",
Self::CollectionParams => {
"edge storage is configured via LocalExecutorOptions, not collection PARAMS"
}
Self::Acorn => "ACORN is a clustered Qdrant HNSW search feature unavailable offline",
Self::Timeout => "qql-edge runs in-process without network RPC timeouts",
Self::Consistency => {
"qql-edge is a single-node in-process engine without replica consistency levels"
}
Self::RecommendAverageVector => {
"qdrant-edge recommend supports best_score and sum_scores only"
}
Self::PointReferenceQuery => {
"offline path must materialize vectors (TEXT/VECTOR) before search"
}
Self::Route { .. } => "this route is not implemented by the edge backend",
}
}
pub fn remote_hint(self) -> Option<&'static str> {
match self {
Self::CollectionParams | Self::PointReferenceQuery => None,
Self::RecommendAverageVector => {
Some("Use STRATEGY best_score or sum_scores offline, or remote Qdrant for average_vector")
}
_ => Some("Use remote Qdrant (REST or gRPC) for this feature"),
}
}
pub fn message(self) -> String {
let mut msg = format!(
"{} is not supported offline: {}.",
self.feature(),
self.why()
);
if let Some(hint) = self.remote_hint() {
msg.push(' ');
msg.push_str(hint);
msg.push('.');
}
msg
}
pub fn error(self) -> QqlError {
QqlError::execution(self.code(), self.message(), None)
}
}
pub fn reject_shard_key(shard_key: Option<&str>) -> Result<(), QqlError> {
if shard_key.is_some() {
Err(EdgeUnsupported::ShardRouting.error())
} else {
Ok(())
}
}
pub fn reject_collection_sharding(
shard_number: Option<u64>,
sharding_method: Option<&str>,
shard_keys: Option<&[String]>,
) -> Result<(), QqlError> {
if shard_number.is_some() || sharding_method.is_some() || shard_keys.is_some() {
Err(EdgeUnsupported::CollectionSharding.error())
} else {
Ok(())
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn catalog_codes_are_stable_and_unique_for_primary_features() {
let features = [
EdgeUnsupported::GroupBy,
EdgeUnsupported::ShardRouting,
EdgeUnsupported::CollectionSharding,
EdgeUnsupported::ShardKeyDdl,
EdgeUnsupported::AlterCollection,
EdgeUnsupported::CollectionParams,
EdgeUnsupported::Acorn,
EdgeUnsupported::RecommendAverageVector,
EdgeUnsupported::PointReferenceQuery,
];
let mut codes = std::collections::BTreeSet::new();
for f in features {
assert!(
f.code().starts_with("QQL-EDGE-UNSUPPORTED-"),
"{}",
f.code()
);
if matches!(f, EdgeUnsupported::CollectionSharding) {
assert_eq!(f.code(), EdgeUnsupported::ShardRouting.code());
} else {
assert!(codes.insert(f.code()), "duplicate code {}", f.code());
}
let msg = f.message();
assert!(!msg.is_empty());
assert!(
msg.contains("not supported offline") || msg.contains("not supported"),
"{msg}"
);
if f.remote_hint().is_some() {
assert!(
msg.to_ascii_lowercase().contains("remote")
|| msg.to_ascii_lowercase().contains("best_score"),
"expected remediation in: {msg}"
);
}
}
}
#[test]
fn group_by_message_mentions_query_groups_and_remote() {
let e = EdgeUnsupported::GroupBy.error();
assert_eq!(e.code, "QQL-EDGE-UNSUPPORTED-GROUP-BY");
assert!(e.message.contains("query groups"));
assert!(e.message.contains("remote Qdrant"));
}
}