Skip to content

World's first open-source enterprise world model.

A class's instance list can keep only the members that lack a given relation, so a client finds the statements without a test without asking once per entity or exporting the base (#1270)

Szabo Bogdan05e6f5af8cdf
diff --git a/crates/utopia-server/src/api/ontology_routes.rs b/crates/utopia-server/src/api/ontology_routes.rs
index 5c66b7c5..9a2a21ce 100644
--- a/crates/utopia-server/src/api/ontology_routes.rs
+++ b/crates/utopia-server/src/api/ontology_routes.rs
@@ -7,6 +7,7 @@ use serde::Deserialize;
use serde_json::json;
use utopia_core::models::Role;
use utopia_core::AppError;
+use utopia_store::ontology::{Lacking, LinkEnd};
use uuid::Uuid;
use crate::auth::{AuthUser, SessionOrToken};
@@ -44,26 +45,83 @@ pub struct InstancesQuery {
pub page: i64,
#[serde(default = "default_per")]
pub per: i64,
+ /// 只列缺这条关系的成员:属性的 key,或一个开放短语(#1269)
+ #[serde(default)]
+ pub missing_predicate: Option<String>,
+ /// out(缺省,成员是主语)| in(成员是宾语)| either
+ #[serde(default)]
+ pub missing_direction: Option<String>,
}
fn default_per() -> i64 {
12
}
+/// 「缺哪条关系、看哪一端」:没给谓词就是不筛;给了空谓词或认不得的方向是 422
+fn missing_link(q: &InstancesQuery) -> Result<Option<(&str, LinkEnd)>, AppError> {
+ let end = match q.missing_direction.as_deref() {
+ None | Some("out") => LinkEnd::Out,
+ Some("in") => LinkEnd::In,
+ Some("either") => LinkEnd::Either,
+ Some(other) => {
+ return Err(AppError::invalid(
+ "bad_missing_direction",
+ format!("missing_direction must be out, in or either, not `{other}`"),
+ ))
+ }
+ };
+ let Some(predicate) = q.missing_predicate.as_deref() else {
+ return Ok(None);
+ };
+ if predicate.trim().is_empty() {
+ return Err(AppError::invalid(
+ "bad_missing_predicate",
+ "missing_predicate must name a relation or a phrase",
+ ));
+ }
+ Ok(Some((predicate.trim(), end)))
+}
+
/// 某个类下的实体实例列表(详情区右侧,分页)。
+/// 带 `missing_predicate` 时只列缺那条关系的成员,并回显认作它的属性与短语。
pub async fn list_entity_instances(
State(state): State<AppState>,
AuthUser(user): AuthUser,
Path((kb_id, type_id)): Path<(Uuid, Uuid)>,
Query(q): Query<InstancesQuery>,
) -> ApiResult<Json<serde_json::Value>> {
+ let missing = missing_link(&q)?;
require_kb(&state, &user, kb_id, Role::Viewer).await?;
let per = q.per.clamp(1, 100);
let page = q.page.max(0);
- let (rows, total) =
- utopia_store::ontology::entity_instances(&state.pool, kb_id, type_id, per, page * per)
- .await?;
- Ok(Json(json!({ "entities": rows, "total": total })))
+ let predicate = match missing {
+ Some((p, end)) => Some((
+ utopia_store::ontology::link_predicate(&state.pool, kb_id, p).await?,
+ end,
+ )),
+ None => None,
+ };
+ let lacking = predicate.as_ref().map(|(predicate, end)| Lacking {
+ predicate,
+ end: *end,
+ });
+ let (rows, total) = utopia_store::ontology::entity_instances(
+ &state.pool,
+ kb_id,
+ type_id,
+ lacking,
+ per,
+ page * per,
+ )
+ .await?;
+ let mut body = json!({ "entities": rows, "total": total });
+ if let Some((p, _)) = &predicate {
+ body["missing"] = json!({
+ "relation_type_id": p.relation_type_id,
+ "phrases": p.phrases(),
+ });
+ }
+ Ok(Json(body))
}
#[derive(Deserialize)]
@@ -815,3 +873,49 @@ pub async fn approve_refinement(
.await;
Ok(Json(json!({ "moved": moved, "batch": batch })))
}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ fn query(predicate: Option<&str>, direction: Option<&str>) -> InstancesQuery {
+ InstancesQuery {
+ page: 0,
+ per: 12,
+ missing_predicate: predicate.map(str::to_owned),
+ missing_direction: direction.map(str::to_owned),
+ }
+ }
+
+ fn code(r: Result<Option<(&str, LinkEnd)>, AppError>) -> &'static str {
+ match r {
+ Err(AppError::Invalid { code, .. }) => code,
+ _ => "",
+ }
+ }
+
+ #[test]
+ fn a_missing_link_reads_its_predicate_and_end() {
+ assert_eq!(missing_link(&query(None, None)).ok(), Some(None));
+ assert_eq!(
+ missing_link(&query(Some(" works_for "), None)).ok(),
+ Some(Some(("works_for", LinkEnd::Out)))
+ );
+ assert_eq!(
+ missing_link(&query(Some("acquired"), Some("either"))).ok(),
+ Some(Some(("acquired", LinkEnd::Either)))
+ );
+ }
+
+ #[test]
+ fn a_blank_predicate_or_an_unknown_end_is_422() {
+ assert_eq!(
+ code(missing_link(&query(Some(" "), None))),
+ "bad_missing_predicate"
+ );
+ assert_eq!(
+ code(missing_link(&query(Some("works_for"), Some("up")))),
+ "bad_missing_direction"
+ );
+ }
+}
diff --git a/crates/utopia-store/src/ontology.rs b/crates/utopia-store/src/ontology.rs
index 0b86f343..32ff379a 100644
--- a/crates/utopia-store/src/ontology.rs
+++ b/crates/utopia-store/src/ontology.rs
@@ -34,37 +34,173 @@ pub async fn entity_type_views(pool: &PgPool, kb_id: Uuid) -> AppResult<Vec<Enti
.await?)
}
+/// 「缺这条关系」看实体在哪一端:Out = 它是主语,In = 它是宾语,Either = 哪端都算。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum LinkEnd {
+ Out,
+ In,
+ Either,
+}
+
+/// 一个谓词在库里能以哪些样子出现,按「实体是关系的主语」这一端说。
+///
+/// 类型化行写的是属性;开放陈述写的是文档的短语,绑定(`phrase_bindings`)说哪些短语
+/// 算这个属性、哪个方向。逆关系与对称关系把「主语」翻成「宾语」:`A parentOf B` 就是
+/// `B childOf A`,所以缺 parentOf 的 A 也得没有一条「X childOf A」。
+#[derive(Debug, Clone)]
+pub struct LinkPredicate {
+ /// 谓词是本体里某个属性的 key 时,那个属性
+ pub relation_type_id: Option<Uuid>,
+ along: Vec<Uuid>,
+ against: Vec<Uuid>,
+ phrases_along: Vec<String>,
+ phrases_against: Vec<String>,
+}
+
+impl LinkPredicate {
+ /// 认作这个谓词的全部短语(归一过的),两个方向合在一起
+ pub fn phrases(&self) -> Vec<String> {
+ let mut all = [self.phrases_along.clone(), self.phrases_against.clone()].concat();
+ all.sort();
+ all.dedup();
+ all
+ }
+}
+
+/// 把一个谓词(属性的 key,或者一个开放短语)解析成它在库里的各种写法。
+pub async fn link_predicate(
+ pool: &PgPool,
+ kb_id: Uuid,
+ predicate: &str,
+) -> AppResult<LinkPredicate> {
+ let (relation_type_id, against, mut phrases_along, phrases_against): (
+ Option<Uuid>,
+ Vec<Uuid>,
+ Vec<String>,
+ Vec<String>,
+ ) = sqlx::query_as(
+ "WITH r AS (SELECT id, inverse_of, is_symmetric FROM relation_types
+ WHERE kb_id = $1 AND key = $2),
+ inv AS (SELECT x.id FROM relation_types x, r
+ WHERE x.kb_id = $1 AND (x.id = r.inverse_of OR x.inverse_of = r.id)
+ UNION SELECT id FROM r WHERE is_symmetric),
+ b AS (SELECT phrase, direction = 'forward' AS fwd,
+ relation_type_id IN (SELECT id FROM r) AS on_r,
+ relation_type_id IN (SELECT id FROM inv) AS on_inv
+ FROM phrase_bindings
+ WHERE kb_id = $1 AND status = 'bound')
+ SELECT (SELECT id FROM r),
+ ARRAY(SELECT id FROM inv),
+ ARRAY(SELECT DISTINCT phrase FROM b
+ WHERE (on_r AND fwd) OR (on_inv AND NOT fwd)),
+ ARRAY(SELECT DISTINCT phrase FROM b
+ WHERE (on_r AND NOT fwd) OR (on_inv AND fwd))",
+ )
+ .bind(kb_id)
+ .bind(predicate)
+ .fetch_one(pool)
+ .await?;
+ phrases_along.push(crate::phrase_bindings::normalize(predicate));
+ Ok(LinkPredicate {
+ relation_type_id,
+ along: relation_type_id.into_iter().collect(),
+ against,
+ phrases_along,
+ phrases_against,
+ })
+}
+
+/// 只列缺某条关系的成员(#1269):没有一条活着的事实(断言、陈述或派生)按这个谓词连着它。
+#[derive(Debug, Clone, Copy)]
+pub struct Lacking<'a> {
+ pub predicate: &'a LinkPredicate,
+ pub end: LinkEnd,
+}
+
+impl Lacking<'_> {
+ /// 实体当主语时认哪些 (属性, 短语),当宾语时认哪些
+ fn arms(&self) -> [(Vec<Uuid>, Vec<String>); 2] {
+ let p = self.predicate;
+ let along = (p.along.clone(), p.phrases_along.clone());
+ let against = (p.against.clone(), p.phrases_against.clone());
+ match self.end {
+ LinkEnd::Out => [along, against],
+ LinkEnd::In => [against, along],
+ LinkEnd::Either => {
+ let both = ([along.0, against.0].concat(), [along.1, against.1].concat());
+ [both.clone(), both]
+ }
+ }
+ }
+}
+
+/// 一端一个 NOT EXISTS,各自走 (kb_id, subject_id) / (kb_id, object_id) 的活行索引
+fn lacking_sql() -> String {
+ let phrase = crate::phrase_bindings::phrase_sql("f.phrase");
+ ["subject", "object"]
+ .iter()
+ .zip([("$3", "$4"), ("$5", "$6")])
+ .map(|(end, (ids, phrases))| {
+ format!(
+ " AND NOT EXISTS (SELECT 1 FROM facts f
+ WHERE f.kb_id = e.kb_id AND f.{end}_id = e.id AND f.invalidated_at IS NULL
+ AND (f.predicate_id = ANY({ids})
+ OR (f.layer = 'open' AND {phrase} = ANY({phrases}))))
+ AND NOT EXISTS (SELECT 1 FROM derived_facts d
+ WHERE d.kb_id = e.kb_id AND d.{end}_id = e.id AND d.invalidated_at IS NULL
+ AND d.predicate_id = ANY({ids}))"
+ )
+ })
+ .collect()
+}
+
/// 某个类下的实体实例(按名称序,分页)。返回 (rows, total)。
+/// 给了 `lacking` 就只留缺那条关系的成员,页与总数按同一个条件数。
pub async fn entity_instances(
pool: &PgPool,
kb_id: Uuid,
type_id: Uuid,
+ lacking: Option<Lacking<'_>>,
limit: i64,
offset: i64,
) -> AppResult<(Vec<EntityInstance>, i64)> {
- let rows: Vec<EntityInstance> = sqlx::query_as(
+ // 没给 lacking 时 $3..$6 是空数组,条件里不引用它们
+ let [(subject_ids, subject_phrases), (object_ids, object_phrases)] =
+ lacking.map(|l| l.arms()).unwrap_or_default();
+ let condition = format!(
+ "e.kb_id = $1 AND e.type_id = $2 AND e.merged_into IS NULL{}",
+ lacking.map(|_| lacking_sql()).unwrap_or_default()
+ );
+ let rows: Vec<EntityInstance> = sqlx::query_as(&format!(
"SELECT e.id, e.canonical_name AS name,
(SELECT count(*) FROM facts f
WHERE f.kb_id = e.kb_id
AND (f.subject_id = e.id OR f.object_id = e.id)
AND f.invalidated_at IS NULL) AS fact_count
FROM entities e
- WHERE e.kb_id = $1 AND e.type_id = $2 AND e.merged_into IS NULL
+ WHERE {condition}
ORDER BY lower(e.canonical_name), e.id
- LIMIT $3 OFFSET $4",
- )
+ LIMIT $7 OFFSET $8"
+ ))
.bind(kb_id)
.bind(type_id)
+ .bind(&subject_ids)
+ .bind(&subject_phrases)
+ .bind(&object_ids)
+ .bind(&object_phrases)
.bind(limit)
.bind(offset)
.fetch_all(pool)
.await?;
- let (total,): (i64,) = sqlx::query_as(
- "SELECT count(*) FROM entities e
- WHERE e.kb_id = $1 AND e.type_id = $2 AND e.merged_into IS NULL",
- )
+ let (total,): (i64,) = sqlx::query_as(&format!(
+ "SELECT count(*) FROM entities e WHERE {condition}"
+ ))
.bind(kb_id)
.bind(type_id)
+ .bind(&subject_ids)
+ .bind(&subject_phrases)
+ .bind(&object_ids)
+ .bind(&object_phrases)
.fetch_one(pool)
.await?;
Ok((rows, total))
diff --git a/crates/utopia-store/src/phrase_bindings.rs b/crates/utopia-store/src/phrase_bindings.rs
index 2d62a0d8..502a739c 100644
--- a/crates/utopia-store/src/phrase_bindings.rs
+++ b/crates/utopia-store/src/phrase_bindings.rs
@@ -17,7 +17,7 @@ use uuid::Uuid;
/// SQL 侧的归一:与 [`normalize`] 一致。`$col` 由调用处替换成列名。
const PHRASE_SQL: &str = "lower(btrim(regexp_replace($col, '\\s+', ' ', 'g')))";
-fn phrase_sql(col: &str) -> String {
+pub(crate) fn phrase_sql(col: &str) -> String {
PHRASE_SQL.replace("$col", col)
}
diff --git a/crates/utopia-store/tests/store/an_instance_list_names_what_a_type_lacks.rs b/crates/utopia-store/tests/store/an_instance_list_names_what_a_type_lacks.rs
new file mode 100644
index 00000000..130e3a6d
--- /dev/null
+++ b/crates/utopia-store/tests/store/an_instance_list_names_what_a_type_lacks.rs
@@ -0,0 +1,116 @@
+//! 一个类的实例列表能只列缺某条关系的成员(#1269)。
+//!
+//! 「哪些人没写雇主」:连着的方式不止类型化的一行——开放陈述照文档的字写(大小写、
+//! 空白不同也是同一个短语)、逆关系从另一头写(`Acme employs Cy`)、绑到这个属性的
+//! 短语(`is employed by`)、规则推出来的一行也算。五种连上的成员都不列,只剩真的什么
+//! 都没有的那个。
+//!
+//! 没有 `UTOPIA_DATABASE_URL` 时跳过而不是失败。自建自拆,绝不碰已有的库。
+
+use sqlx::PgPool;
+use utopia_store::ontology::{entity_instances, link_predicate, Lacking, LinkEnd};
+use uuid::Uuid;
+
+const ORG: &str = "instances-lacking-test";
+
+async fn names_lacking(
+ pool: &PgPool,
+ kb: Uuid,
+ person: Uuid,
+ predicate: &str,
+ end: LinkEnd,
+) -> anyhow::Result<(Vec<String>, i64)> {
+ let predicate = link_predicate(pool, kb, predicate).await?;
+ let lacking = Lacking {
+ predicate: &predicate,
+ end,
+ };
+ let (rows, total) = entity_instances(pool, kb, person, Some(lacking), 50, 0).await?;
+ Ok((rows.into_iter().map(|r| r.name).collect(), total))
+}
+
+#[tokio::test]
+async fn a_member_linked_any_way_is_not_listed_as_lacking() -> anyhow::Result<()> {
+ let Some(url) = utopia_store::test_db::url() else {
+ return Ok(());
+ };
+ let pool = PgPool::connect(&url).await?;
+ sqlx::query("DELETE FROM organizations WHERE name = $1")
+ .bind(ORG)
+ .execute(&pool)
+ .await?;
+ let id = Uuid::now_v7;
+ let (org, ws, kb, person, company) = (id(), id(), id(), id(), id());
+ let (works_for, employs) = (id(), id());
+ let (ann, bo, cy, dee, eve, fay, acme) = (id(), id(), id(), id(), id(), id(), id());
+ sqlx::raw_sql(&format!(
+ r#"
+ INSERT INTO organizations (id, name) VALUES ('{org}', '{ORG}');
+ INSERT INTO workspaces (id, org_id, name) VALUES ('{ws}', '{org}', '{ORG}');
+ INSERT INTO knowledge_bases (id, workspace_id, name) VALUES ('{kb}', '{ws}', '{ORG}');
+ INSERT INTO entity_types (id, kb_id, key, label) VALUES
+ ('{person}', '{kb}', 'person', 'Person'),
+ ('{company}', '{kb}', 'company', 'Company');
+ INSERT INTO relation_types (id, kb_id, key, label) VALUES
+ ('{works_for}', '{kb}', 'works_for', 'worksFor');
+ INSERT INTO relation_types (id, kb_id, key, label, inverse_of) VALUES
+ ('{employs}', '{kb}', 'employs', 'employs', '{works_for}');
+ INSERT INTO entities (id, kb_id, type_id, canonical_name) VALUES
+ ('{ann}', '{kb}', '{person}', 'Ann'), ('{bo}', '{kb}', '{person}', 'Bo'),
+ ('{cy}', '{kb}', '{person}', 'Cy'), ('{dee}', '{kb}', '{person}', 'Dee'),
+ ('{eve}', '{kb}', '{person}', 'Eve'), ('{fay}', '{kb}', '{person}', 'Fay'),
+ ('{acme}', '{kb}', '{company}', 'Acme');
+ -- 类型化、逆关系从另一头写
+ INSERT INTO facts (id, kb_id, subject_id, predicate_id, object_id) VALUES
+ ('{f1}', '{kb}', '{ann}', '{works_for}', '{acme}'),
+ ('{f2}', '{kb}', '{acme}', '{employs}', '{cy}');
+ -- 开放陈述:照写的短语、绑到属性的短语;Dee 只有一条不相干的
+ INSERT INTO facts (id, kb_id, subject_id, object_id, layer, phrase) VALUES
+ ('{f3}', '{kb}', '{bo}', '{acme}', 'open', ' Works_For'),
+ ('{f4}', '{kb}', '{eve}', '{acme}', 'open', 'is employed by'),
+ ('{f5}', '{kb}', '{dee}', '{ann}', 'open', 'mentors');
+ INSERT INTO phrase_bindings (id, kb_id, phrase, subject_type_id, object_type_id,
+ relation_type_id, direction, status) VALUES
+ ('{b1}', '{kb}', 'is employed by', '{person}', '{company}',
+ '{works_for}', 'forward', 'bound');
+ INSERT INTO rules (id, kb_id, predicate_id, kind) VALUES
+ ('{rule}', '{kb}', '{works_for}', 'transitive');
+ INSERT INTO derived_facts (id, kb_id, subject_id, predicate_id, object_id, rule_id) VALUES
+ ('{d1}', '{kb}', '{fay}', '{works_for}', '{acme}', '{rule}');
+ "#,
+ f1 = id(),
+ f2 = id(),
+ f3 = id(),
+ f4 = id(),
+ f5 = id(),
+ b1 = id(),
+ rule = id(),
+ d1 = id(),
+ ))
+ .execute(&pool)
+ .await?;
+
+ let lacking_employer = names_lacking(&pool, kb, person, "works_for", LinkEnd::Out).await?;
+ assert_eq!(lacking_employer, (vec!["Dee".to_owned()], 1));
+ let predicate = link_predicate(&pool, kb, "works_for").await?;
+ assert_eq!(predicate.relation_type_id, Some(works_for));
+ assert_eq!(predicate.phrases(), ["is employed by", "works_for"]);
+
+ // 开放短语、看宾语那端:只有 Ann 被人 mentors 过
+ let never_mentored = names_lacking(&pool, kb, person, "Mentors", LinkEnd::In).await?;
+ assert_eq!(
+ never_mentored,
+ (
+ ["Bo", "Cy", "Dee", "Eve", "Fay"]
+ .map(str::to_owned)
+ .to_vec(),
+ 5
+ )
+ );
+
+ sqlx::query("DELETE FROM organizations WHERE id = $1")
+ .bind(org)
+ .execute(&pool)
+ .await?;
+ Ok(())
+}
diff --git a/crates/utopia-store/tests/store/main.rs b/crates/utopia-store/tests/store/main.rs
index 44d9280c..b263d456 100644
--- a/crates/utopia-store/tests/store/main.rs
+++ b/crates/utopia-store/tests/store/main.rs
@@ -111,6 +111,7 @@ mod an_end_date_closes_the_open_span;
mod an_event_holds_at_the_moment_it_names;
mod an_exploration_says_what_it_covered;
mod an_export_carries_the_whole_ledger;
+mod an_instance_list_names_what_a_type_lacks;
mod an_open_statement_keeps_the_documents_words;
mod an_sso_login_finds_or_opens_its_account;
mod an_undeclared_name_is_looked_up;
diff --git a/docs/design/ontology.md b/docs/design/ontology.md
index 0e1cfee9..60dfcd6e 100644
--- a/docs/design/ontology.md
+++ b/docs/design/ontology.md
@@ -49,6 +49,14 @@ classes of context neighbours, interleaved and never scored together; a class in
subtree applied on its own, a cross-axis class sent to a person, each pair acknowledged once) runs
from the ontology page; extraction no longer enqueues it [0001, 0016, #736].
+**A class's member list can name what its members lack** [#1269]. The instance list
+(`GET /kbs/{id}/ontology/entity-types/{type_id}/entities`) takes `missing_predicate`, a property key
+or an open phrase, and `missing_direction` (`out`, the default, with the member as subject; `in`;
+`either`), and keeps only the members no live fact links by that predicate: a typed row, a derived
+row, a row of the inverse (or symmetric) property from the other end, an open statement whose phrase
+normalizes to it, or one whose phrase is bound to the property. The answer echoes what was matched
+(`missing.relation_type_id`, `missing.phrases`); membership itself is unchanged (`entities.type_id`).
+
**One statement draws one edge** [#755]. The typed graph is a view, so the canvas and the entity
panel show one edge per statement: the property's name when a live typed row was computed from it,
the document's phrase when none was. The document's wording is not lost with the folded edge, it