docs(timestream-influxdb-mcp-server): Add schema design, query, and ingestion guidance - #9
Conversation
trevorbonas
changed the title
…d ingestion guides (#10) * Add InfluxDB v2 and v3 query guides * Add ingestion guides for InfluxDB v2 and v3 (#11) * Add ingestion guides for InfluxDB v2 and v3 * Direct agents to query-guide.md for schema guidance * Apply suggestion from @fredjoonpark Co-authored-by: j00n <fred.park@improving.com> * Apply suggestion from @fredjoonpark Co-authored-by: j00n <fred.park@improving.com> --------- Co-authored-by: j00n <fred.park@improving.com> * Specify that Content-Type is required for v2 query requests * Remove Content-Type header from InfluxDB v3 GET requests * Add query parameter details for InfluxDB v3 query requests * Refer to db as DATABASE_NAME in all InfluxDB v3 query documentation * Fix broken curl command for v2 query guide * Change chunked_size to chunk_size * Remove Content-Type for example InfluxDB v3 GET request * Remove extra bracket in timestamp comment * Remove duplicate keywords from InfluxDB v3 query guide * Change accept_partial default to true * Fix epoch options in write_lp * Add json body POST v2 example --------- Co-authored-by: j00n <fred.park@improving.com>
trevorbonas
changed the title
…n differences for InfluxDB v2 and v3 (#12)
fredjoonpark
left a comment
fredjoonpark
left a comment
There was a problem hiding this comment.
let's also add a section to the README pointing to our power.md, similar to:
https://github.com/Bit-Quill/mcp/blob/main/src/aurora-dsql-mcp-server/README.md#kiro-power - though their linked power is broken. we can link to our power.md here instead.
also, let's move POWER.md + steering into a folder called kiro_power (following pattern i see in the other svcs)
I've tried my best to replicate that section in our I've renamed |
fredjoonpark
left a comment
fredjoonpark
left a comment
There was a problem hiding this comment.
in getting-started, we should also use links to the referenced docs
| ### V3 — cluster only | ||
| Timestream for InfluxDB 3 is **always deployed as a cluster** (`create-db-cluster`). There is no single-instance API for V3. The cluster's topology is determined by the parameter group, not a `--deployment-type` flag (do **not** pass `--deployment-type` for V3): | ||
|
|
||
| - **Core** (`InfluxDBV3Core`) — a **single-node** cluster. Ingestion, querying, compaction, and the processing engine all run on one node and share compute. Core has **no dedicated compactor**, so it is best for recent data (typically the last 3–5 days). |
There was a problem hiding this comment.
does casing matter in the actual API? ie
if it does, let's make it consistent across all our docs (V3 vs v3), for both core and enterprise params.
There was a problem hiding this comment.
The casing matters. InfluxDBV3Enterprise and InfluxDBV3Core are the names and IDs of service-owned parameter groups. When creating parameter groups, InfluxDBv3Core and InfluxDBv3Enterprise are used to specify options. I've clarified this through all documentation.
There was a problem hiding this comment.
wow how annoying. I wonder if this should be fixed on the service side, feel like this can very easily confuse agents (and humans). what do you think?
There was a problem hiding this comment.
At this point, with all of their users, I doubt Timestream would want to change this, even if it were possible.
There was a problem hiding this comment.
maybe they could at least relax the constraint?
There was a problem hiding this comment.
Timestream could relax the constraint of lower and upper casing? We can reach out to them. It's not in scope for the PR.
fredjoonpark
left a comment
fredjoonpark
left a comment
There was a problem hiding this comment.
@trevorbonas have you confirmed you can actually load the power with the MCP and see it in action? and how did you verify, is this shareable in some way?
| - Target **5,000+ points per request** minimum | ||
| - Optimal batch size: 5,000–10,000 points | ||
| - Max recommended: ~50,000 points per request (beyond this, HTTP timeouts become a risk) | ||
| - For high-throughput workloads, tune write timeout in the parameter group (see Tuning section below) |
There was a problem hiding this comment.
I dont see a write timeout parameter, can we add it to the tuning section?
There was a problem hiding this comment.
Not applicable for V3 so I instead recommend scaling vertically or horizontally.
| @@ -65,8 +66,8 @@ Design principle: same as V2 — **one database per retention period**. | |||
| Guidance: | |||
| - Create databases via `POST /api/v3/configure/database`. | |||
| - Retention is set via `retentionPeriod` (e.g. `"7d"`, `"90d"`, `"1y"`). Null or omitted = infinite. | |||
There was a problem hiding this comment.
we use retention_period in the example, but use retentionPeriod in descriptions (also at https://github.com/Bit-Quill/mcp/pull/9/changes#diff-57bc8c6d85c993e16ba46f78352a762d1cf98e0e985e00b727878da8fb20012dR12) - do both work? can we make it consistent?
There was a problem hiding this comment.
Changed to retention_period. That's what the HTTP V3 API expects.
|
|
||
| ## Best Practices | ||
|
|
||
| - SHOULD ask user about which version of InfluxDB they are using if not specified. |
There was a problem hiding this comment.
let's include onboarding guides here for as well, as it's the main getting started doc
3 participants
Fixes
Summary
Changes
Adds schema design details for InfluxDB v2.
User experience
Checklist
If your change doesn't seem to apply, please leave them unchecked.
Is this a breaking change? (Y/N)
RFC issue number:
Checklist:
Acknowledgment
By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of the project license.