three-frogs-bathe/docs/TAYLORDB_QUERY_REFERENCE.md

TaylorDB Query Builder Reference

This is the entry point for all TaylorDB query builder docs in this template.
The content has been split into smaller, focused files to make it easier for agents (and humans) to scan and reuse.

---

📚 Topics

• Basic Reads & Filtering
  See TAYLORDB_BASIC_QUERIES.md for:

  • Basic selectFrom usage
  • Ordering
  • where clauses
  • Date filters
  • Array/select field filters
  • Text search (contains)

• Write Operations (Insert, Update, Delete)
  See TAYLORDB_WRITE_OPERATIONS.md for:

  • Inserting records (including single-/multi-select fields)
  • Updates (single/multiple fields, conditional updates)
  • Bulk updates
  • Deleting single/multiple records and conditional deletes

• Advanced Patterns
  See TAYLORDB_ADVANCED_PATTERNS.md for:

  • Manual aggregations
  • Summation helpers
  • Conditional query builders
  • Pagination patterns

• Field Types & Enums
  See TAYLORDB_FIELD_TYPES.md for:

  • TaylorDB field type → TypeScript mappings
  • Nullable field handling
  • Using generated enum options (...Options) types

• Attachments
  See TAYLORDB_ATTACHMENTS.md for:

  • Selecting attachment fields
  • Creating/updating records with attachments via uploadAttachments

• Pitfalls & Best Practices
  See TAYLORDB_PITFALLS_BEST_PRACTICES.md for:

  • Common mistakes (e.g., forgetting ["exactDay", date], misusing execute)
  • Recommended patterns for safe, type-accurate queries

---

How Agents Should Use These Docs

1. Start from your use case

   • Need a simple read? Open TAYLORDB_BASIC_QUERIES.md.
   • Doing writes? Use TAYLORDB_WRITE_OPERATIONS.md.
   • Need aggregations or pagination? Use TAYLORDB_ADVANCED_PATTERNS.md.

2. Combine with generated types
   Always cross-reference:

   • apps/server/taylordb/types.ts (schema-derived types)
   • apps/server/taylordb/query-builder.ts (project-specific query functions)

3. Check pitfalls before finalizing
   Before shipping queries, skim TAYLORDB_PITFALLS_BEST_PRACTICES.md to avoid common errors.

---

Additional Resources

• Generated Types: apps/server/taylordb/types.ts
• Example Queries in This Template: apps/server/taylordb/query-builder.ts
• tRPC Integration: apps/server/router.ts

---

Note: These docs mirror the TaylorDB query builder patterns used in this template.
For the most up-to-date API details, always refer to the official TaylorDB documentation.