Implementation Example

D1 Database Integration

Transform your data access layer. Business intent drives query construction, performance profiles, and data quality requirements — not scattered technical flags.

The Anti-Pattern

Technical query parameters drive data retrieval. Flags like isQuick determine which records to return, mixing technical concerns with business intent.

✗ Anti-Pattern

// Technical flags driving data retrieval - WRONG
const reports = await db.prepare(`
  SELECT * FROM reports
  WHERE status = ? AND priority = ?
`).bind(isQuick ? 'draft' : 'published', level).all();

Semantic Query Builder

The semantic approach derives query intent from business context — who is requesting data, why they need it, and what quality level is required.

✓ Semantic Intent

// Business intent driving data semantics - CORRECT
const semanticQuery = SemanticQueryBuilder.forIntent(userIntent);
const reports = await semanticQuery.executeAsync(db);

Deriving Data Intent

User role and purpose determine everything: data scope, urgency, quality requirements, and performance profile. An executive making a decision gets authoritative, sub-2s data. An analyst doing research gets comprehensive data at a relaxed pace.

static deriveFromRequest(request: DataRequest): DataSemanticIntent {
  const userContext = this.determineUserContext(
    request.userRole, request.purpose
  );
  const dataScope = this.determineDataScope(
    userContext, request.dataSubject
  );

  return {
    dataScope,        // ExecutiveSummary | Comprehensive | RealTime
    urgencyContext,    // Critical (<100ms) | Standard (<10s) | Background
    userContext,       // ExecutiveDecision | AnalyticalResearch
    qualityRequirements, // Authoritative | Analytical | Exploratory
    performanceProfile,  // Instantaneous | Interactive | Batch
  };
}

Adaptive Query Construction

The query builder adapts its SQL strategy based on semantic intent. Executives get aggregated KPIs. Monitoring contexts get the last hour of data. Historical analysis gets time-series queries.

private buildBaseQuery(): string {
  switch (this.intent.dataScope) {
    case DataScope.ExecutiveSummary:
      return `
        SELECT DATE(created_at) as date,
               COUNT(*) as total_count,
               AVG(performance_score) as avg_performance,
               SUM(revenue) as total_revenue
        FROM reports r`;

    case DataScope.RealTimeMonitoring:
      return `
        SELECT r.*, pm.current_status, pm.last_updated
        FROM reports r
        WHERE r.created_at > datetime('now', '-1 hour')`;
    // ...
  }
}

Semantic Mapping Rules

User Context	Data Scope	Quality	Performance
Executive Decision	Summary	Authoritative	< 2s
Managerial Review	Operational	Business-ready	< 10s
Analytical Research	Comprehensive	Analytical	Background
System Monitoring	Real-time	Indicative	< 100ms