From 69bb7e4a38434fe6e3be7cbd4e746ab9789128f9 Mon Sep 17 00:00:00 2001 From: Hemant <104012423+hemant838@users.noreply.github.com> Date: Wed, 8 Apr 2026 12:19:00 +0530 Subject: [PATCH] Close #2718 : added querying with prefix patterns example and documentation (#2778) * feat: add querying with prefix patterns example and documentation * refine --------- Co-authored-by: Reynaldi Chernando --- src/docs/src/KV.md | 1 + src/docs/src/KV/list.md | 69 +++++++++++++++++++ src/docs/src/examples.js | 12 +++- .../examples/kv-prefix-patterns.html | 62 +++++++++++++++++ 4 files changed, 141 insertions(+), 3 deletions(-) create mode 100644 src/docs/src/playground/examples/kv-prefix-patterns.html diff --git a/src/docs/src/KV.md b/src/docs/src/KV.md index fb0b79e9a..9d0e885d3 100644 --- a/src/docs/src/KV.md +++ b/src/docs/src/KV.md @@ -232,6 +232,7 @@ You can see various Puter.js Key-Value Store features in action from the followi - [Decrement](/playground/kv-decr/) - [Delete](/playground/kv-del/) - [List](/playground/kv-list/) +- [Querying with Prefix Patterns](/playground/kv-prefix-patterns/) - [Flush](/playground/kv-flush/) - [Expire](/playground/kv-expire/) - [Expire At](/playground/kv-expireAt/) diff --git a/src/docs/src/KV/list.md b/src/docs/src/KV/list.md index 03b950b90..6f467d761 100755 --- a/src/docs/src/KV/list.md +++ b/src/docs/src/KV/list.md @@ -6,6 +6,8 @@ platforms: [websites, apps, nodejs, workers] Returns an array of all keys in the user's key-value store for the current app. If the user has no keys, the array will be empty. +Because filtering is prefix-based, `list()` works best when you design keys around the read patterns your app needs. In practice, that means your key naming convention becomes your query plan. + Results are sorted lexicographically (string order) by key. ## Syntax @@ -193,3 +195,70 @@ If the user has no keys, the array will be empty. ``` + +Design keys for query-like filtering with prefix patterns + +```html;kv-prefix-patterns + + + + + + +``` diff --git a/src/docs/src/examples.js b/src/docs/src/examples.js index d84a493ed..ad51999b5 100644 --- a/src/docs/src/examples.js +++ b/src/docs/src/examples.js @@ -418,13 +418,19 @@ const examples = [ description: 'See how keys are returned in lexicographic order with puter.kv.list(). Run and modify this example in the playground.', slug: 'kv-list-sort', source: '/playground/examples/kv-list-sort.html', - }, - { + }, + { title: 'List (Zero-Padding)', description: 'Learn how to sort numeric keys correctly by zero-padding. Run and experiment with this example in the playground.', slug: 'kv-list-padding', source: '/playground/examples/kv-list-padding.html', - }, + }, + { + title: 'List (Prefix Patterns)', + description: 'Learn how to model SQL-style filtering in Puter.js KV by designing keys for prefix queries. Run and modify this example in the playground.', + slug: 'kv-prefix-patterns', + source: '/playground/examples/kv-prefix-patterns.html', + }, { title: 'Flush', description: 'Clear all data with Puter.js key-value API. Run and experiment with this flush example in the playground.', diff --git a/src/docs/src/playground/examples/kv-prefix-patterns.html b/src/docs/src/playground/examples/kv-prefix-patterns.html new file mode 100644 index 000000000..5af28cf4c --- /dev/null +++ b/src/docs/src/playground/examples/kv-prefix-patterns.html @@ -0,0 +1,62 @@ + + + + + +