Skip to content

YC (S26) | Open Computer History | Continuously record your company computer work, map your workflows, help you find work worth automating, and power your agents' context

Batch accessibility-element inserts instead of one RETURNING-id round-trip per node (#5042)

Ezra Ellettefd40e261fc71
diff --git a/crates/screenpipe-db/src/db/frames.rs b/crates/screenpipe-db/src/db/frames.rs
index e9f331f6f..509f4e1d5 100644
--- a/crates/screenpipe-db/src/db/frames.rs
+++ b/crates/screenpipe-db/src/db/frames.rs
@@ -380,8 +380,14 @@ impl DatabaseManager {
/// Insert accessibility tree nodes from `tree_json` (serialized
/// `Vec<AccessibilityTreeNode>`) into the `elements` table.
///
- /// Nodes are inserted in depth-first order. A depth→parent_id stack is
- /// used to resolve parent references.
+ /// Nodes are inserted in depth-first order. Ids are reserved up front
+ /// (contiguous block starting after `sqlite_sequence`'s current value
+ /// for `elements`) so a depth→parent_id stack can resolve parent
+ /// references before any row is written, letting the whole tree go in
+ /// as a handful of multi-row INSERTs instead of one `RETURNING id`
+ /// round-trip per node. Safe because the write queue serializes all
+ /// writes onto a single connection — nothing else can consume ids
+ /// between the reservation read and the batch insert below.
///
/// Errors are logged and swallowed.
pub(crate) async fn insert_accessibility_elements(
@@ -455,12 +461,35 @@ impl DatabaseManager {
return;
}
+ // Reserve a contiguous id block up front instead of RETURNING id
+ // per row. `elements.id` is AUTOINCREMENT, so sqlite_sequence holds
+ // the last assigned value; the next row (auto or explicit) is
+ // seq + 1, and explicit inserts above the current seq bump it for
+ // later auto-assigned rows (OCR elements, etc.) exactly as if they
+ // had been auto-assigned themselves.
+ let base_id: i64 = match sqlx::query_scalar::<_, i64>(
+ "SELECT COALESCE((SELECT seq FROM sqlite_sequence WHERE name = 'elements'), 0)",
+ )
+ .fetch_one(&mut **tx)
+ .await
+ {
+ Ok(v) => v,
+ Err(e) => {
+ debug!(
+ "elements: AX id reservation failed for frame {}: {}",
+ frame_id, e
+ );
+ return;
+ }
+ };
+
// depth → most-recent element_id at that depth
// parent of depth N = last id at depth N-1
let mut depth_stack: Vec<(u8, i64)> = Vec::new();
- let mut sort_order: i32 = 0;
+ let mut rows: Vec<AxRow<'_>> = Vec::with_capacity(nodes.len());
- for node in &nodes {
+ for (i, node) in nodes.iter().enumerate() {
+ let id = base_id + 1 + i as i64;
let depth = node.depth as i32;
let text = if node.text.is_empty() {
None
@@ -558,37 +587,43 @@ impl DatabaseManager {
// 20260502000000_add_elements_on_screen.sql skips legacy rows.
let on_screen_int: Option<i64> = node.on_screen.map(|b| if b { 1 } else { 0 });
- let result = sqlx::query_scalar::<_, i64>(
- "INSERT INTO elements (frame_id, source, role, text, parent_id, depth, left_bound, top_bound, width_bound, height_bound, confidence, sort_order, properties, on_screen) VALUES (?1, 'accessibility', ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, NULL, ?10, ?11, ?12) RETURNING id",
- )
- .bind(frame_id)
- .bind(&node.role)
- .bind(text)
- .bind(parent_id)
- .bind(depth)
- .bind(left)
- .bind(top)
- .bind(width)
- .bind(height)
- .bind(sort_order)
- .bind(&properties)
- .bind(on_screen_int)
- .fetch_one(&mut **tx)
- .await;
+ // Trim stack to current depth, then push this node's reserved id
+ while depth_stack.last().is_some_and(|(d, _)| *d as i32 >= depth) {
+ depth_stack.pop();
+ }
+ depth_stack.push((node.depth, id));
+
+ rows.push(AxRow {
+ id,
+ role: &node.role,
+ text,
+ parent_id,
+ depth,
+ left,
+ top,
+ width,
+ height,
+ sort_order: i as i32,
+ properties,
+ on_screen: on_screen_int,
+ });
+ }
- match result {
- Ok(id) => {
- // Trim stack to current depth, then push
- while depth_stack.last().is_some_and(|(d, _)| *d as i32 >= depth) {
- depth_stack.pop();
- }
- depth_stack.push((node.depth, id));
- sort_order += 1;
- }
- Err(e) => {
- debug!("elements: AX insert failed for frame {}: {}", frame_id, e);
- return;
- }
+ // 13 params per row × 70 rows = 910 params, well below SQLite's
+ // default SQLITE_LIMIT_VARIABLE_NUMBER (999 on older builds, 32766 on
+ // newer). Chunk boundaries never split a parent from a child that
+ // hasn't been inserted yet: node order is depth-first, so within
+ // each chunk (and across chunks, since earlier chunks are already
+ // executed) every parent id was assigned — and inserted — before
+ // any of its children.
+ const BULK_CHUNK: usize = 70;
+ for chunk in rows.chunks(BULK_CHUNK) {
+ if let Err(e) = flush_ax_bulk(tx, frame_id, chunk).await {
+ debug!(
+ "elements: AX bulk insert failed for frame {}: {}",
+ frame_id, e
+ );
+ return;
}
}
}
diff --git a/crates/screenpipe-db/src/db/mod.rs b/crates/screenpipe-db/src/db/mod.rs
index 0a121941f..8a3675acd 100644
--- a/crates/screenpipe-db/src/db/mod.rs
+++ b/crates/screenpipe-db/src/db/mod.rs
@@ -295,6 +295,73 @@ async fn flush_level0_bulk(
Ok(())
}
+/// One accessibility-tree element row, buffered for bulk insertion. `id` is
+/// reserved client-side (see `DatabaseManager::insert_accessibility_elements`)
+/// so `parent_id` references are known before any row is written.
+struct AxRow<'a> {
+ id: i64,
+ role: &'a str,
+ text: Option<&'a str>,
+ parent_id: Option<i64>,
+ depth: i32,
+ left: Option<f64>,
+ top: Option<f64>,
+ width: Option<f64>,
+ height: Option<f64>,
+ sort_order: i32,
+ properties: Option<String>,
+ on_screen: Option<i64>,
+}
+
+/// Bulk-insert a batch of accessibility elements with pre-assigned ids.
+/// Because ids are reserved up front, a whole frame's tree can go in as one
+/// multi-row INSERT instead of N `RETURNING id` round-trips — the win is
+/// specific to accessibility because every node (not just leaves) can be a
+/// parent, so the old code paid a round-trip per node. Row order must keep
+/// each parent before its children within the statement: SQLite checks
+/// immediate foreign keys (`elements.parent_id -> elements.id`, enabled by
+/// sqlx's default `PRAGMA foreign_keys = ON`) as each row lands, so a child
+/// row would fail FK validation if its parent hasn't been inserted yet in
+/// this same statement. Depth-first tree order already guarantees this.
+async fn flush_ax_bulk(
+ tx: &mut sqlx::pool::PoolConnection<Sqlite>,
+ frame_id: i64,
+ chunk: &[AxRow<'_>],
+) -> Result<(), sqlx::Error> {
+ if chunk.is_empty() {
+ return Ok(());
+ }
+ let mut sql = String::with_capacity(260 + chunk.len() * 60);
+ sql.push_str(
+ "INSERT INTO elements (id, frame_id, source, role, text, parent_id, depth, left_bound, top_bound, width_bound, height_bound, confidence, sort_order, properties, on_screen) VALUES ",
+ );
+ for i in 0..chunk.len() {
+ if i > 0 {
+ sql.push(',');
+ }
+ sql.push_str("(?,?,'accessibility',?,?,?,?,?,?,?,?,NULL,?,?,?)");
+ }
+ let mut q = sqlx::query(&sql);
+ for row in chunk {
+ q = q
+ .bind(row.id)
+ .bind(frame_id)
+ .bind(row.role)
+ .bind(row.text)
+ .bind(row.parent_id)
+ .bind(row.depth)
+ .bind(row.left)
+ .bind(row.top)
+ .bind(row.width)
+ .bind(row.height)
+ .bind(row.sort_order)
+ .bind(row.properties.as_deref())
+ .bind(row.on_screen);
+ }
+ q.execute(&mut **tx).await?;
+ Ok(())
+}
+
mod accessibility;
mod audio;
mod display_layout;
diff --git a/crates/screenpipe-db/src/db/tests.rs b/crates/screenpipe-db/src/db/tests.rs
index 64cec2bb7..f93488ab7 100644
--- a/crates/screenpipe-db/src/db/tests.rs
+++ b/crates/screenpipe-db/src/db/tests.rs
@@ -563,3 +563,144 @@ fn test_cluster_mixed_scenario() {
assert_eq!(groups[1].group_size, 2); // Gmail group
assert_eq!(groups[2].group_size, 1); // Maps group 2 (separate visit)
}
+
+/// Synthetic accessibility-tree JSON with `n` nodes in depth-first
+/// pre-order, branching factor `branch`, capped at depth 12 (real AX trees
+/// rarely go deeper). Mirrors the field set real captures serialize —
+/// container nodes carry no text, leaves do — so the batch insert exercises
+/// the same `properties`/`text`/`parent_id` shapes as production.
+#[cfg(test)]
+fn synth_ax_tree_json(n: usize, branch: usize) -> String {
+ fn rec(nodes: &mut Vec<serde_json::Value>, target: usize, depth: u8, branch: usize) {
+ if nodes.len() >= target {
+ return;
+ }
+ let is_leaf = depth >= 12 || branch == 0;
+ nodes.push(serde_json::json!({
+ "role": if is_leaf { "AXStaticText" } else { "AXGroup" },
+ "text": if is_leaf { format!("leaf-{}", nodes.len()) } else { String::new() },
+ "depth": depth,
+ }));
+ if is_leaf {
+ return;
+ }
+ for _ in 0..branch {
+ if nodes.len() >= target {
+ return;
+ }
+ rec(nodes, target, depth + 1, branch);
+ }
+ }
+ let mut nodes = Vec::with_capacity(n);
+ while nodes.len() < n {
+ rec(&mut nodes, n, 0, branch);
+ }
+ serde_json::to_string(&nodes).unwrap()
+}
+
+#[cfg(test)]
+async fn seed_frame_for_elements(db: &DatabaseManager) -> i64 {
+ sqlx::query("INSERT INTO video_chunks (file_path, device_name) VALUES ('/tmp/x.mp4', 'dev')")
+ .execute(&db.pool)
+ .await
+ .unwrap();
+ sqlx::query_scalar(
+ "INSERT INTO frames (video_chunk_id, offset_index, timestamp) \
+ VALUES (1, 0, '2026-07-09T00:00:00Z') RETURNING id",
+ )
+ .fetch_one(&db.pool)
+ .await
+ .unwrap()
+}
+
+/// Correctness: the batched insert must reproduce the exact tree shape
+/// (parent/child links, depth, sort_order) the old per-row
+/// `INSERT ... RETURNING id` path produced, including across bulk-chunk
+/// boundaries (chunk size is 70 — 200 nodes spans three flushes).
+#[tokio::test]
+async fn ax_bulk_insert_preserves_tree_shape_across_chunks() {
+ for n in [1usize, 69, 70, 71, 200, 574] {
+ let db = DatabaseManager::new("sqlite::memory:", Default::default())
+ .await
+ .unwrap();
+ let frame_id = seed_frame_for_elements(&db).await;
+ let tree_json = synth_ax_tree_json(n, 4);
+
+ let mut conn = db.pool.acquire().await.unwrap();
+ DatabaseManager::insert_accessibility_elements(&mut conn, frame_id, &tree_json).await;
+ drop(conn);
+
+ let count: i64 = sqlx::query_scalar("SELECT COUNT(*) FROM elements WHERE frame_id = ?1")
+ .bind(frame_id)
+ .fetch_one(&db.pool)
+ .await
+ .unwrap();
+ assert_eq!(count as usize, n, "row count mismatch for n={}", n);
+
+ // Every non-root row's parent_id must point at a row exactly one
+ // depth shallower that was already inserted (smaller id) — the
+ // FK would have already rejected forward references, but we also
+ // check depth semantics match the source tree.
+ let rows: Vec<(i64, Option<i64>, i32, i32)> = sqlx::query_as(
+ "SELECT id, parent_id, depth, sort_order FROM elements \
+ WHERE frame_id = ?1 ORDER BY sort_order ASC",
+ )
+ .bind(frame_id)
+ .fetch_all(&db.pool)
+ .await
+ .unwrap();
+
+ assert_eq!(rows.len(), n);
+ for (i, (id, parent_id, _depth, sort_order)) in rows.iter().enumerate() {
+ assert_eq!(
+ *sort_order, i as i32,
+ "sort_order mismatch for n={} idx={}",
+ n, i
+ );
+ if let Some(pid) = parent_id {
+ assert!(
+ *pid < *id,
+ "parent id must precede child id for n={} idx={}",
+ n,
+ i
+ );
+ }
+ }
+ }
+}
+
+/// Measures wall-clock time of the batched accessibility-element insert
+/// across realistic tree sizes. Not a pass/fail perf gate (CI hardware
+/// varies too much for a stable threshold) — run with
+/// `cargo test -p screenpipe-db --release -- --ignored --nocapture perf_ax_bulk_insert`
+/// to see the numbers.
+#[tokio::test]
+#[ignore = "manual perf measurement, see doc comment"]
+async fn perf_ax_bulk_insert_measurement() {
+ for n in [50usize, 200, 574, 2000, 5000] {
+ let db = DatabaseManager::new("sqlite::memory:", Default::default())
+ .await
+ .unwrap();
+ let frame_id = seed_frame_for_elements(&db).await;
+ let tree_json = synth_ax_tree_json(n, 4);
+ let mut conn = db.pool.acquire().await.unwrap();
+
+ let start = std::time::Instant::now();
+ DatabaseManager::insert_accessibility_elements(&mut conn, frame_id, &tree_json).await;
+ let elapsed = start.elapsed();
+
+ let count: i64 = sqlx::query_scalar("SELECT COUNT(*) FROM elements WHERE frame_id = ?1")
+ .bind(frame_id)
+ .fetch_one(&db.pool)
+ .await
+ .unwrap();
+ assert_eq!(count as usize, n);
+
+ println!(
+ "n={:<5} elapsed={:>8.3}ms ({:.3}us/node)",
+ n,
+ elapsed.as_secs_f64() * 1000.0,
+ elapsed.as_secs_f64() * 1_000_000.0 / n as f64
+ );
+ }
+}