docs: Add docs for new runtime parameters feature #296
Conversation
📝 WalkthroughWalkthroughThe documentation was updated to expand guidance on optimizing vector similarity searches, now including advice on tuning runtime parameters. Additionally, a new document was added that introduces and explains the use of runtime parameters in Serverpod for fine-tuning PostgreSQL query execution, with detailed examples and descriptions for vector search optimization. Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant Docs
User->>Docs: Reads about vector similarity search optimization
Docs-->>User: Suggests creating vector indexes and tuning runtime parameters
User->>Docs: Reads runtime parameters documentation
Docs-->>User: Explains global/local parameters, vector search options, and code examples
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (4)
docs/06-concepts/06-database/12-runtime-parameters.md (4)
38-49: Import context for combined groups example
This snippet builds on the previous one but reuses the same types. Recommend adding a note that thepackage:serverpod/serverpod.dartimport applies here as well for clarity.
59-85: Include import for VectorIndexQueryOptions
The general vector optimization example introducesVectorIndexQueryOptionswithout an import. Suggest adding:import 'package:serverpod/serverpod.dart';to the top of the snippet.
107-120: Add import for IVFFLAT options
The IVFFLAT example usesIvfFlatIndexQueryOptionsbut lacks an import. Recommend adding:import 'package:serverpod/serverpod.dart';
124-128: Minor punctuation in enum description
Add a comma for clarity in the relaxed scan description:-Allows slightly out-of-order results but provides better recall. +Allows slightly out-of-order results, but provides better recall.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
docs/06-concepts/06-database/06-filter.md(1 hunks)docs/06-concepts/06-database/12-runtime-parameters.md(1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/06-concepts/06-database/12-runtime-parameters.md
[uncategorized] ~126-~126: Loose punctuation mark.
Context: ... scanning: - IterativeScan.strict: Ensures results are in exact order by d...
(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~127-~127: Loose punctuation mark.
Context: ...recision). - IterativeScan.relaxed: Allows slightly out-of-order results bu...
(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~127-~127: Possible missing comma found.
Context: ...**: Allows slightly out-of-order results but provides better recall. ## Setting glo...
(AI_HYDRA_LEO_MISSING_COMMA)
⏰ Context from checks skipped due to timeout of 90000ms (1)
- GitHub Check: Test build
🔇 Additional comments (6)
docs/06-concepts/06-database/12-runtime-parameters.md (5)
1-3: Strong title and concise intro
The heading and introduction clearly explain the purpose and benefit of runtime parameters.
5-7: Clear cautionary warning
The warning block effectively highlights risks of tuning database parameters without testing.
9-15: Well-defined parameter scopes
The explanation of global vs. local scopes is precise and easy to follow.
87-104: HNSW optimization snippet is complete
This section includes the import and all necessary details forHnswIndexQueryOptions. No changes needed.
130-152: Caution: internal API import
Importing frompackage:serverpod/src/server/serverpod.dartaccesses internal APIs that may change. Confirm that this is intended and consider warning users about potential breaking changes in future releases.docs/06-concepts/06-database/06-filter.md (1)
274-277: Verify link to runtime parameters
The tip now references[runtime parameters](runtime-parameters). Please confirm this anchor resolves correctly in the generated site.
| ```dart | ||
| var hnswOptions = HnswIndexQueryOptions(efSearch: 40); | ||
|
|
||
| // Global scope - affects all queries in this session | ||
| await session.db.setRuntimeParameters([hnswOptions]); | ||
|
|
||
| // Local scope - only affects current transaction | ||
| await session.db.transaction((transaction) async { | ||
| await session.db.setRuntimeParameters([hnswOptions], transaction: transaction); | ||
|
|
||
| var results = await Document.db.find( | ||
| session, | ||
| where: (t) => t.embedding.distanceCosine(queryVector) < 0.5, | ||
| limit: 10, | ||
| orderBy: (t) => t.embedding.distanceCosine(queryVector), | ||
| transaction: transaction, | ||
| ); | ||
|
|
||
| return results; | ||
| }); | ||
| ``` |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Add import for serverpod package
The Dart snippet uses HnswIndexQueryOptions but omits the required import. To ensure the example compiles, add at the top:
import 'package:serverpod/serverpod.dart';🤖 Prompt for AI Agents
In docs/06-concepts/06-database/12-runtime-parameters.md around lines 16 to 36,
the Dart code snippet uses HnswIndexQueryOptions but does not include the
necessary import statement. Add the import line "import
'package:serverpod/serverpod.dart';" at the top of the code snippet to ensure it
compiles correctly.
Add docs for the new
setRuntimeParameterfeature as implemented on Serverpod's PR 3627.Summary by CodeRabbit