YouTrackDB Documentation

The current generation of the YouTrackDB cost-based planner is designed to be correct and fast for common cases, but it relies on coarse estimates and greedy search patterns. For developers looking to contribute, the project has identified several key areas for 'second generation' improvements. These improvements are interconnected, with some serving as foundations for others.

Key areas for contribution include:

• Cardinality Estimation (v2): Improving how the engine estimates record counts (addressing triples, skew, and correlation).
• Join Order Enumeration: Moving from greedy DFS to a more robust IDP enumerative planner.
• Stats-drift Management: Implementing plan-cache invalidation when statistics change.
• Hash-join Improvements: Adding spill-to-disk capabilities.
• EXPLAIN Observability: Enhancing the ability to debug and observe the planner's decisions.

If you are looking for the lowest-risk entry point to contribute, the documentation recommends starting with EXPLAIN observability (§18.5), as it makes all other improvements easier to measure and debug.

YouTrackDB is a general-purpose object-oriented graph database designed for both embedded and client-server deployment models. It is developed by JetBrains and features:

• Fast Link Traversal: O(1) complexity for link traversal without expensive runtime JOINs.
• Object-Oriented Model: Supports inheritance and polymorphism at the database level.
• Snapshot Isolation: All transactions run under snapshot isolation by default, preventing dirty reads, non-repeatable reads, and phantom reads.
• Query Languages: Supports Gremlin (via TinkerPop API) and YQL (YouTrackDB Query Language), a SQL-based language with graph extensions like dot notation for traversal and MATCH statements for pattern matching.
• Flexible Schemas: Supports schema-less, schema-mixed, and schema-full modes.
• Security & Encryption: Strong security profiling (user, role, and predicate policies) and optional encryption of data at rest.
• High Availability Features: Online incremental and full backups that allow reads and writes to continue during the process.

The house-style.md file is organized into ten top-level H2 sections that move from high-level tone to specific structural rules:

1. What this style governs: Defines the scope of application.
2. BLUF lead: Focuses on Bottom Line Up Front.
3. Voice and tone: Establishes the project's persona.
4. Banned vocabulary: Categorized into four tiers (Hard ban, Strongly avoid, Promotional, and Era-specific).
5. Banned sentence patterns: Targets patterns like negative parallelism, throat-clearing, and trailing hedges.
6. Banned analysis patterns: Targets humanizer-gap patterns like superficial -ing analysis, hedge stacking, and vague attribution.
7. Punctuation and typography: Rules for em-dashes, hyphens, curly quotes, and boldface.
8. Structural rules: Rules for heading hierarchy and list usage.
9. Document-shape rules: Specific rules for design docs and ADRs (e.g., 'Why-before-what', 'Overview concept-first').
10. Self-check: A final checklist for authors.

The jmh-ldbc project is organized into several key components for benchmarking YouTrackDB against LDBC workloads:

Core Java Classes

• LdbcBenchmarkState: Manages the database lifecycle, data loading, and access to curated parameters.
• ParameterCurator: Handles factor tables, gap-based grouping, and per-query parameter generation.
• LdbcQuerySql: Responsible for loading SQL query strings from classpath resources.
• LdbcDatabaseTool: A CLI utility for export, import, backup, and restore operations.
• LdbcExplainTool: Provides EXPLAIN and PROFILE capabilities for all queries.

Benchmark Base Classes

Benchmarks are categorized by workload type and performance characteristics:

• LdbcISUltraFastBenchmarkBase: IS1, IS3-6, IC13 (Fastest).
• LdbcISBenchmarkBase: IS2, IS7, IC8 (Noisy).
• LdbcICBenchmarkBase: IC2, IC7, IC11.
• LdbcICSlowBenchmarkBase: IC1, 4, 6, 9, 12.
• LdbcICUltraSlowBenchmarkBase: IC3, 5, 10 (Slowest).

Threading Models

• LdbcSingleThread{...}Benchmark: Runs with @Threads(1).
• LdbcMultiThread{...}Benchmark: Runs with @Threads(MAX).

YouTrackDB uses a zero-copy mechanism for reading records to eliminate byte[] copying. Instead of copying bytes from the disk cache into a new array, the system keeps a reference to the disk cache PageFrame within the EntityImpl object.

How it works:

1. Optimistic Read Path: The storage layer returns a RawPageBuffer containing PageFrame coordinates.
2. Speculative Deserialization: EntityImpl stores these coordinates and deserializes properties directly from the PageFrame's ByteBuffer at the time of access.
3. Validation: A StampedLock stamp captured during the read is validated after deserialization.
4. Fallback: If the stamp is invalid (indicating the page changed), the system performs a one-shot fallback by re-reading the record through the pinned storage path into a standard byte[].

This approach touches the deserialization container, guard allocations, storage read results, and the EntityImpl lifecycle.

The readability-auditor agent includes a secondary guard to detect 'wiring errors' where the orchestrator fails to properly slice a large document. This guard prevents a single-slice audit from being performed on a document that exceeds a specific length threshold, which would otherwise be a violation of the required 'Range-sliced fan-out' pattern.

Guard Trigger Condition: The guard fires and reports a blocker wiring error if and only if:

1. slice_count == 1
2. total_lines > 300

Key Constraints:

• Exact Threshold: The floor is exactly 300 lines. While the orchestrator uses approximate targets (e.g., ~200-line windows), the guard uses the exact integer for deterministic pass/fail logic.
• Param-Presence Gating: The guard only runs if both slice_count and total_lines are present in the auditor's parameters. If these fields are missing, the auditor proceeds with a normal slice audit. This allows legitimate single-pass spawns (like design-sync) to function without being flagged as errors.
• S1 Invariant Safety: The slice_count and total_lines are considered slicing metadata, not prose conclusions. Passing them does not violate the 'cold-read' guarantee because they do not prime the reader with information about the document's content.

// Example of parameters that trigger the guard
{
  "target": "...",
  "target_path": "...",
  "range": "...",
  "slice_count": 1,
  "total_lines": 350
}
// Result: Reports a 'blocker' wiring error

To prevent vacuous findings during dimensional reviews (Phase B/C), the system uses a triage mechanism in .claude/workflow/review-agent-selection.md.

When a git diff contains only workflow-machinery files (located under .claude/, root CLAUDE.md, or docs/adr/<dir>/_workflow/), the system applies a baseline-skip override. This skips the four Java-focused baseline agents (review-code-quality, review-bugs-concurrency, review-test-behavior, review-test-completeness) and instead dispatches the Workflow-review agents group.

Workflow-review agents and finding-prefix mappings:

• WC: Workflow Consistency
• WP: Workflow Planning
• WI: Workflow Implementation
• WH: Workflow Hooks
• WB: Workflow Bugs
• WS: Workflow Style

Trigger patterns for workflow agents:

• review-workflow-consistency: Any workflow-machinery file.
• review-workflow-hook-safety: .claude/hooks/*.sh, .claude/scripts/**, or .claude/settings*.json.
• review-workflow-writing-style: .claude/**/*.md, root CLAUDE.md, or docs/adr/**/*.md.