[{"data":1,"prerenderedAt":545},["ShallowReactive",2],{"navigation_docs":3,"-scale-benchmarks":152,"-scale-benchmarks-surround":540},[4,27,65,95,109,131],{"title":5,"icon":6,"path":7,"stem":8,"children":9,"page":26},"Getting started","i-lucide-play","\u002Fstart","1.start",[10,14,18,22],{"title":11,"path":12,"stem":13},"Introduction","\u002Fstart\u002Fintroduction","1.start\u002F1.introduction",{"title":15,"path":16,"stem":17},"Installation","\u002Fstart\u002Finstallation","1.start\u002F2.installation",{"title":19,"path":20,"stem":21},"Quick start","\u002Fstart\u002Fquick-start","1.start\u002F3.quick-start",{"title":23,"path":24,"stem":25},"How a request is handled","\u002Fstart\u002Fhow-it-works","1.start\u002F4.how-it-works",false,{"title":28,"icon":29,"path":30,"stem":31,"children":32,"page":26},"Resources","i-lucide-boxes","\u002Fresource","2.resource",[33,37,41,45,49,53,57,61],{"title":34,"path":35,"stem":36},"Engine","\u002Fresource\u002Fengine","2.resource\u002F1.engine",{"title":38,"path":39,"stem":40},"Define a resource","\u002Fresource\u002Fdefine-a-resource","2.resource\u002F2.define-a-resource",{"title":42,"path":43,"stem":44},"Relations","\u002Fresource\u002Frelations","2.resource\u002F3.relations",{"title":46,"path":47,"stem":48},"Scope","\u002Fresource\u002Fscope","2.resource\u002F4.scope",{"title":50,"path":51,"stem":52},"Field rules","\u002Fresource\u002Ffield-policy","2.resource\u002F5.field-policy",{"title":54,"path":55,"stem":56},"Models","\u002Fresource\u002Fmodels","2.resource\u002F6.models",{"title":58,"path":59,"stem":60},"Views","\u002Fresource\u002Fviews","2.resource\u002F7.views",{"title":62,"path":63,"stem":64},"Summaries","\u002Fresource\u002Fsummaries","2.resource\u002F8.summaries",{"title":66,"icon":67,"path":68,"stem":69,"children":70,"page":26},"Queries","i-lucide-send","\u002Fquery","3.query",[71,75,79,83,87,91],{"title":72,"path":73,"stem":74},"Request shape","\u002Fquery\u002Frequest-shape","3.query\u002F1.request-shape",{"title":76,"path":77,"stem":78},"Filters","\u002Fquery\u002Ffilters","3.query\u002F2.filters",{"title":80,"path":81,"stem":82},"Search","\u002Fquery\u002Fsearch","3.query\u002F3.search",{"title":84,"path":85,"stem":86},"Sorting","\u002Fquery\u002Fsorting","3.query\u002F4.sorting",{"title":88,"path":89,"stem":90},"Pagination","\u002Fquery\u002Fpagination","3.query\u002F5.pagination",{"title":92,"path":93,"stem":94},"Facets","\u002Fquery\u002Ffacets","3.query\u002F6.facets",{"title":96,"icon":97,"path":98,"stem":99,"children":100,"page":26},"Endpoints","i-lucide-server","\u002Fserve","4.serve",[101,105],{"title":102,"path":103,"stem":104},"Validation","\u002Fserve\u002Fvalidation","4.serve\u002F1.validation",{"title":106,"path":107,"stem":108},"Types","\u002Fserve\u002Ftyped-clients","4.serve\u002F2.typed-clients",{"title":110,"icon":111,"path":112,"stem":113,"children":114,"page":26},"Performance","i-lucide-gauge","\u002Fscale","5.scale",[115,119,123,127],{"title":116,"path":117,"stem":118},"Tuning","\u002Fscale\u002Fperformance","5.scale\u002F1.performance",{"title":120,"path":121,"stem":122},"Strategies","\u002Fscale\u002Fstrategies","5.scale\u002F2.strategies",{"title":124,"path":125,"stem":126},"Bulk scans","\u002Fscale\u002Fbulk-scans","5.scale\u002F3.bulk-scans",{"title":128,"path":129,"stem":130},"Benchmarks","\u002Fscale\u002Fbenchmarks","5.scale\u002F4.benchmarks",{"title":132,"icon":133,"path":134,"stem":135,"children":136,"page":26},"Reference","i-lucide-book-open","\u002Freference","6.reference",[137,141,145,148],{"title":138,"path":139,"stem":140},"Methods","\u002Freference\u002Fmethods","6.reference\u002F1.methods",{"title":142,"path":143,"stem":144},"Filter builder","\u002Freference\u002Ffilter-builder","6.reference\u002F2.filter-builder",{"title":106,"path":146,"stem":147},"\u002Freference\u002Ftypes","6.reference\u002F3.types",{"title":149,"path":150,"stem":151},"Strategy utils","\u002Freference\u002Fstrategy-utils","6.reference\u002F4.strategy-utils",{"id":153,"title":128,"body":154,"description":533,"extension":534,"links":535,"meta":536,"navigation":537,"path":129,"seo":538,"stem":130,"__hash__":539},"docs\u002F5.scale\u002F4.benchmarks.md",{"type":155,"value":156,"toc":525},"minimark",[157,166,171,178,184,196,200,207,213,220,224,231,237,240,244,252,261,267,270,274,277,282,286,521],[158,159,160,161,165],"p",{},"Every number below comes from an orders table with ",[162,163,164],"strong",{},"200,000 rows",", measured without HTTP: the engine's own cost, not your API's latency. Timings are medians of ten runs from one client, unless the section is about load.",[167,168,170],"h2",{"id":169},"what-a-request-costs","What a request costs",[158,172,173,174,177],{},"Returning a page is almost free, even 180,000 rows deep with a cursor. What you pay for is ",[162,175,176],{},"counting",": an exact total reads every matching row, and facets group them again. Leave both off when the screen doesn't show them.",[179,180],"bench-bars",{":rows":181,"title":182,"caption":183},"[{\"label\":\"Page\",\"note\":\"rows only\",\"value\":0.51,\"hot\":true},{\"label\":\"Cursor page\",\"note\":\"180,000 rows in\",\"value\":1.09,\"hot\":true},{\"label\":\"1,000 ids filter\",\"value\":2.76,\"hot\":true},{\"label\":\"Page + exact count\",\"value\":4.17},{\"label\":\"Search a relation + count\",\"value\":16.8},{\"label\":\"3 facets\",\"note\":\"one statement\",\"value\":24.76},{\"label\":\"Filtered facets\",\"note\":\"each ignores its own filter\",\"value\":35.84},{\"label\":\"5 facets\",\"note\":\"two statements\",\"value\":57.38}]","Time per request","Yellow: no count and no facets.",[158,185,186,187,191,192,195],{},"Facets on the root table share one ",[188,189,190],"code",{},"GROUPING SETS"," statement. Facets that read relations need their own, which is why five mixed facets cost more than three root ones. See ",[193,194,110],"a",{"href":117}," for what to do about each.",[167,197,199],{"id":198},"under-load","Under load",[158,201,202,203,206],{},"With 32 callers sharing 10 pooled connections, and PostgreSQL held to 4 CPUs, a plain page serves about ",[162,204,205],{},"11,500 requests a second",". Counting is again what limits you: an exact count brings that to about 730, and five facets to about 19.",[179,208],{":rows":209,"title":210,"caption":211,"unit":212},"[{\"label\":\"Page\",\"note\":\"p95 3.5 ms\",\"value\":11563,\"hot\":true},{\"label\":\"Cursor page\",\"note\":\"180,000 rows in · p95 8.3 ms\",\"value\":5746,\"hot\":true},{\"label\":\"1,000 ids filter\",\"note\":\"p95 23 ms\",\"value\":1741,\"hot\":true},{\"label\":\"Page + exact count\",\"note\":\"p95 67 ms\",\"value\":729},{\"label\":\"Search a relation + count\",\"note\":\"p95 287 ms\",\"value\":124},{\"label\":\"3 facets\",\"note\":\"p95 476 ms\",\"value\":74},{\"label\":\"Filtered facets\",\"note\":\"p95 1.0 s\",\"value\":32},{\"label\":\"5 facets\",\"note\":\"p95 2.1 s\",\"value\":19}]","Throughput at 32 concurrent callers","20 rounds of 32 requests each. Yellow: no count and no facets.","rps",[158,214,215,216,219],{},"The gap is the amount of work. A page walks the sort index, takes 50 rows and stops; each facet reads and groups all 200,000. With 4 CPUs, that works out to at most about 0.35 ms of database CPU per page, against about 210 ms per five-facet request. Pages and cursors stay under 10 ms at p95 with the pool fully busy. Facet requests are the ones to cache, defer, or ",[193,217,218],{"href":117},"tune"," before you add connections.",[167,221,223],{"id":222},"searching-through-relations","Searching through relations",[158,225,226,227,230],{},"A search on related fields, like ",[188,228,229],{},"customer.name",", can join every order to its customer, or find the matching customers first. The engine asks PostgreSQL which plan is cheaper and picks it.",[179,232],{":rows":233,"title":234,"caption":235,":legend":236},"[{\"label\":\"Rare term, customer\",\"before\":87.04,\"after\":4.14},{\"label\":\"Rare term, reference\",\"before\":85.14,\"after\":6.32},{\"label\":\"Common term\",\"before\":21.52,\"after\":22.82}]","Search with an exact count","Measured on September 21, 2026, when the engine started picking the plan.","[\"one fixed plan\",\"engine picks the plan\"]",[158,238,239],{},"Rare terms get 13 to 21 times faster. Common terms match on the first rows anyway, so asking for the plan just adds about 1 ms.",[167,241,243],{"id":242},"exporting-every-row","Exporting every row",[245,246,248,249],"bench-stat",{"value":247},"900 ms","to stream all 200,000 rows with ",[188,250,251],{},"resource.scan()",[158,253,254,255,260],{},"Paging through the same rows re-runs the whole selection for every page of 1,000. ",[193,256,257],{"href":125},[188,258,259],{},"scan()"," keeps one cursor open instead, and the gap grows with the cost of the sort.",[179,262],{":rows":263,"title":264,":legend":265,"unit":266},"[{\"label\":\"Sorted by date\",\"before\":1.02,\"after\":0.928},{\"label\":\"Sorted by customer\",\"before\":5.177,\"after\":0.853}]","All 200,000 rows","[\"200 page requests\",\"one scan()\"]","s",[158,268,269],{},"A scan holds a connection and a snapshot until your consumer finishes.",[167,271,273],{"id":272},"since-version-241","Since version 2.4.1",[158,275,276],{},"The same requests on version 2.4.1 (September 2026), measured in the same run: before the engine learned to skip redundant joins, share facet statements and seek straight to a cursor.",[278,279],"bench-since",{":legend":280,":rows":281,"title":182},"[\"2.4.1\",\"today\"]","[{\"label\":\"Page\",\"before\":39.95,\"after\":0.51},{\"label\":\"Cursor page, 180,000 in\",\"before\":20.11,\"after\":1.09},{\"label\":\"Page + exact count\",\"before\":62.46,\"after\":4.17},{\"label\":\"Search a relation\",\"before\":79.46,\"after\":16.8},{\"label\":\"3 facets\",\"before\":90.03,\"after\":24.76},{\"label\":\"5 facets\",\"before\":195.04,\"after\":57.38},{\"label\":\"Filtered facets\",\"before\":138.22,\"after\":35.84}]",[167,283,285],{"id":284},"details","Details",[287,288,289,388,469],"accordion",{},[290,291,293,304,357],"accordion-item",{"label":292},"How it was measured, and how to run it",[158,294,295,296,299,300,303],{},"The harness, ",[188,297,298],{},"tools\u002Fbenchmark-postgres.ts",", creates 200,000 orders and 20,000 accounts with indexes on joins, sorts and searched text, checks that both versions return the same results, then alternates their runs: ten samples per request after a warm-up. PostgreSQL 18, ",[188,301,302],{},"work_mem"," 4 MB.",[305,306,311],"pre",{"className":307,"code":308,"language":309,"meta":310,"style":310},"language-bash shiki shiki-themes vitesse-light vitesse-light vitesse-dark","TEST_DATABASE_URL=postgres:\u002F\u002F… \\\nBENCH_BASELINE_MODULE=…\u002Fdrizzle-resource@2.4.1\u002Fbuild\u002Findex.js \\\nbun run benchmark:postgres\n","bash","",[188,312,313,334,345],{"__ignoreMap":310},[314,315,318,322,326,330],"span",{"class":316,"line":317},"line",1,[314,319,321],{"class":320},"svjTx","TEST_DATABASE_URL",[314,323,325],{"class":324},"so0ae","=",[314,327,329],{"class":328},"scWd0","postgres:\u002F\u002F…",[314,331,333],{"class":332},"skGA_"," \\\n",[314,335,337,341],{"class":316,"line":336},2,[314,338,340],{"class":339},"siET0","BENCH_BASELINE_MODULE=…\u002Fdrizzle-resource@2.4.1\u002Fbuild\u002Findex.js ",[314,342,344],{"class":343},"shueU","\\\n",[314,346,348,351,354],{"class":316,"line":347},3,[314,349,350],{"class":339},"bun ",[314,352,353],{"class":328},"run",[314,355,356],{"class":328}," benchmark:postgres\n",[158,358,359,362,363,366,367,370,371,374,375,378,379,387],{},[188,360,361],{},"BENCH_ROWS"," and ",[188,364,365],{},"BENCH_ITERATIONS"," change the size, ",[188,368,369],{},"BENCH_CONCURRENCY"," sends several requests at once (the load section used 32, with the database container limited to 4 CPUs and one request type per process), ",[188,372,373],{},"BENCH_SCAN=1"," adds the full-export comparison, and ",[188,376,377],{},"BENCH_OUTPUT"," writes the JSON results. Raw samples are in ",[193,380,384],{"href":381,"rel":382},"https:\u002F\u002Fgithub.com\u002FChronicStone\u002Fdrizzle-resource\u002Ftree\u002Fmain\u002Ftools\u002Fresults",[383],"nofollow",[188,385,386],{},"tools\u002Fresults",".",[290,389,391,394],{"label":390},"Searching nine fields at once",[158,392,393],{},"Searching every field, numbers included, can't use the indexed rewrite. A common term finds a page fast; a rare one reads the whole selection.",[395,396,397,417],"table",{},[398,399,400],"thead",{},[401,402,403,407,411,414],"tr",{},[404,405,406],"th",{},"Term",[404,408,410],{"align":409},"right","No count",[404,412,413],{"align":409},"Exact count",[404,415,416],{"align":409},"Count + 5 facets",[418,419,420,438,455],"tbody",{},[401,421,422,429,432,435],{},[423,424,425,426],"td",{},"rare, ",[188,427,428],{},"19999",[423,430,431],{"align":409},"144 ms",[423,433,434],{"align":409},"321 ms",[423,436,437],{"align":409},"392 ms",[401,439,440,446,449,452],{},[423,441,442,443],{},"common, ",[188,444,445],{},"account",[423,447,448],{"align":409},"7.0 ms",[423,450,451],{"align":409},"194 ms",[423,453,454],{"align":409},"346 ms",[401,456,457,460,463,466],{},[423,458,459],{},"no match",[423,461,462],{"align":409},"131 ms",[423,464,465],{"align":409},"172 ms",[423,467,468],{"align":409},"274 ms",[290,470,472,475,518],{"label":471},"Earlier tuning runs, under concurrent load",[158,473,474],{},"An older engine on about 100,000 rows, at 10 to 50 concurrent connections. It shows which tuning pays off first, not today's capacity.",[395,476,477,487],{},[398,478,479],{},[401,480,481,484],{},[404,482,483],{},"Step",[404,485,486],{},"Effect",[418,488,489,497,508],{},[401,490,491,494],{},[423,492,493],{},"Indexes on join, sort, filter",[423,495,496],{},"about 8× throughput, p99 down 83 to 87%",[401,498,499,505],{},[423,500,501,502],{},"Hand-written ",[188,503,504],{},"strategy.ids",[423,506,507],{},"about 12× throughput over that engine",[401,509,510,515],{},[423,511,501,512],{},[188,513,514],{},"strategy.facets",[423,516,517],{},"mostly helps many-to-many facets",[158,519,520],{},"Faster pages send more traffic to the facet aggregates, and a many-to-many facet stayed above 2 s at 10 connections whatever the ids step did.",[522,523,524],"style",{},"html pre.shiki code .svjTx, html code.shiki .svjTx{--shiki-light:#B07D48;--shiki-default:#B07D48;--shiki-dark:#BD976A}html pre.shiki code .so0ae, html code.shiki .so0ae{--shiki-light:#999999;--shiki-default:#999999;--shiki-dark:#666666}html pre.shiki code .scWd0, html code.shiki .scWd0{--shiki-light:#B56959;--shiki-default:#B56959;--shiki-dark:#C98A7D}html pre.shiki code .skGA_, html code.shiki .skGA_{--shiki-light:#59873A;--shiki-default:#59873A;--shiki-dark:#80A665}html pre.shiki code .siET0, html code.shiki .siET0{--shiki-light:#393A34;--shiki-default:#393A34;--shiki-dark:#DBD7CAEE}html pre.shiki code .shueU, html code.shiki .shueU{--shiki-light:#A65E2B;--shiki-default:#A65E2B;--shiki-dark:#C99076}html .light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html.light .shiki span {color: var(--shiki-light);background: var(--shiki-light-bg);font-style: var(--shiki-light-font-style);font-weight: var(--shiki-light-font-weight);text-decoration: var(--shiki-light-text-decoration);}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}",{"title":310,"searchDepth":336,"depth":336,"links":526},[527,528,529,530,531,532],{"id":169,"depth":336,"text":170},{"id":198,"depth":336,"text":199},{"id":222,"depth":336,"text":223},{"id":242,"depth":336,"text":243},{"id":272,"depth":336,"text":273},{"id":284,"depth":336,"text":285},"How long the engine takes to answer list requests on a 200,000-row PostgreSQL table, and what makes a request expensive.","md",null,{},true,{"title":128,"description":533},"RYjOrOlxBulzdhOopJmCfbQhg4LlvLmDphyl5DjXvyA",[541,543],{"title":124,"path":125,"stem":126,"description":542,"children":-1},"Read every matching row in bounded batches, for exports and background jobs, with one PostgreSQL cursor.",{"title":138,"path":139,"stem":140,"description":544,"children":-1},"Every method of a resource, what it runs and what it returns.",1795033616747]