Tigergraph

TigerGraph Documentation Audit

The docs cover a large surface (TigerGraph DB, Savanna, GSQL, pyTigerGraph, REST API) but are riddled with version-timeline contradictions, broken navigation, code samples that wouldn't run, and a documented-vs-actual gap between the published pyTigerGraph docs and the shipping client. Agents and human readers will both stumble on the same surfaces.

1. Release timeline on the docs landing page is internally inconsistent (critical)

Location: https://tigergraph.com/docs/home (Announcements section)

Problem: The Announcements list claims "TigerGraph DB 4.1.4 was released on May. 6, 2026" while also showing "TigerGraph DB 4.2.2 was released on September. 30, 2025." A higher version (4.2.2) is listed as having shipped eight months before a lower version (4.1.4). The 4.2 release-notes page corroborates that 4.2.2 LTS shipped 2025-09-30. There is no explanation that 4.1.x is a parallel LTS branch.

Consequence: A developer (or an agent ranking versions) landing on the docs home page cannot tell which version is current, which is LTS, or which to install. The most prominent navigation surface on the entire docs hub is the part that's most confusing.

The fix: Group releases by branch (4.1 LTS, 4.2 LTS, 3.10 LTS) with explicit "current"/"latest" tags. State that 4.1.x and 4.2.x are parallel LTS branches if that is the intent. Also fix the punctuation ("May. 6, 2026" / "September. 30, 2025" — month abbreviations don't take periods when spelled out).

2. No llms.txt or machine-readable doc manifest (significant)

Location: https://tigergraph.com/llms.txt and https://docs.tigergraph.com/llms.txt

Problem: Both /llms.txt and /llms-full.txt return 404 on the marketing site, and the docs subdomain has nothing equivalent — the URL just redirects to /docs/home/. TigerGraph has a large multi-product docs surface (DB, Savanna, GSQL, pyTigerGraph, REST API) and no entry point for agents to discover it.

Consequence: AI coding agents (Claude Code, Cursor, Copilot) indexing TigerGraph have to crawl HTML and guess at structure rather than read a curated map. Given how much the docs lean on cross-product references (Savanna ↔ DB ↔ GSQL ↔ pyTigerGraph), this is exactly the kind of doc set that benefits most from a manifest.

The fix: Publish https://docs.tigergraph.com/llms.txt listing the top-level product hubs (DB 4.2, Savanna, GSQL 4.2, pyTigerGraph, REST API) and key reference URLs, with llms-full.txt for the consolidated reference content. Bonus: an OpenAPI spec for the REST endpoints (see issue 7) feeds into the same discovery story.

3. The "current" DB intro page has a double-word and bare-text navigation (significant)

Location: https://docs.tigergraph.com/tigergraph-server/4.2/intro/

Problem: The intro page that the "current" symlink resolves to literally reads "please see please see the Version Directory" — a double-phrase typo on the very first line. Below that, the entire onboarding navigation table presents section names ("System Requirements", "Installation", "GSQL Shell", "User Access Management", "Security", "Data Connectors", "Database Import/Export", "Metrics Reports", "Log Files", "Audit Logs", "Kubernetes", "Kubernetes Operator") as bare text rather than active hyperlinks.

Consequence: This is the canonical landing page for anyone running TigerGraph DB at the current version. The first thing a developer (or agent) reads is a duplicated phrase, and the next thing they try to do — click into "Installation" — fails because the labels aren't links. They have to fall back to the left-rail sidebar to navigate at all.

The fix: Fix the "please see please see" duplication. Wire each bullet/cell in the Get to Know table to its destination page so the intro acts as the navigation hub it visually claims to be.

4. Savanna landing page repeats the bare-text-navigation problem (significant)

Location: https://docs.tigergraph.com/savanna/main/overview/

Problem: The Savanna landing page consists of one sentence of explanation followed by a "Get to Know TigerGraph Savanna" table whose sub-section labels — "Workgroup", "Workspace", "Pattern Search", "IDP integration with SSO", "Glossary", "Terms and Conditions", "Insights", "GraphStudio", "GraphQL", "Payment Method", "Invoices", "Pricing", "Support" — are bare text, not links.

Consequence: The other half of the product surface (the managed cloud) has the same navigation defect as the DB intro: the page that should be the hub for Savanna documentation forces readers back to the left rail to actually click anything. For an agent following the "Get Started" framing, the next click target is invisible.

The fix: Make every label in the Savanna landing table a working link to its sub-page. Add at least a "What you can do with Savanna" paragraph so the page is more than a navigation manifest.

5. Known-issues table is full of truncated, unactionable rows (significant)

Location: https://docs.tigergraph.com/tigergraph-server/4.2/release-notes/ (Known Issues and Limitations)

Problem: Several rows have descriptions that are literal sentence fragments — "When", "After upgrading, the system fails to detect", "When using", "Using" — paired with "TBD" workarounds and "TBD" fix-versions. The release notes for an LTS database publish unfinished sentences as known issues.

Consequence: An operator reading these rows before upgrading to 4.2.2 will see "After upgrading, the system fails to detect" — found in 4.1.3, workaround TBD, fixed TBD — and either pause the upgrade indefinitely (because what if that's the bug that affects them?) or ignore the table entirely. Either response is the wrong one. An agent answering "what are the known issues in TigerGraph 4.2.2?" will surface the fragments verbatim.

The fix: Finish each row's description, fill in the workaround column (or remove the row if no workaround/fix exists), and gate publishing of the release-notes page on a lint that rejects "TBD" workarounds for already-shipped versions.

6. Certified-OS list publishes versions that have been end-of-life for years (significant)

Location: https://docs.tigergraph.com/tigergraph-server/4.2/installation/hw-and-sw-requirements (Certified Operating Systems table)

Problem: The 4.2 hardware-and-software requirements certify "CentOs 6.5 to 8.0" (CentOS 6/7/8 are all EOL), "Amazon Linux 2016.03 to 2018.03" (deprecated AMIs), and "RedHat (RHEL) 7.0 to 8.9" / "9.0 to 9.2/9.5" — leaving gaps (e.g., RHEL 8.10+). The browser table also lists "Internet Explorer 10+" as supported in a doc dated 2026; Microsoft retired IE in 2022. Bonus typo: "production hardware configuation."

Consequence: A platform team reading this in 2026 cannot tell whether the docs are stale or whether TigerGraph genuinely supports EOL operating systems. They'll either over-trust (and run on unsupported OSes) or under-trust (and not deploy at all without contacting support).

The fix: Drop CentOS entries (or mark explicitly "best-effort, EOL — not recommended"), refresh Amazon Linux to AL2/AL2023, fill the RHEL 8.x/9.x gaps, remove Internet Explorer, and add a "Last updated" date to the table. Fix the "configuation" typo.

7. Region-aware install example uses the same machine ID three times (significant)

Location: https://docs.tigergraph.com/tigergraph-server/4.2/installation/bare-metal-install ("region-aware" NodeList example)

Problem: The example install_conf.json snippet contains:

"r2: m4: 192.168.0.4",
"r3: m4: 192.168.0.5",
"r3: m4: 192.168.0.6"

m4 is used three times across two regions on three different IPs. The intent was clearly m4/m5/m6. Also note the stray " after the closing ].

Consequence: A developer who copy-pastes this and replaces only the IPs gets duplicate node names — TigerGraph will reject the config or silently mis-place the cluster topology. An agent extracting "the canonical cluster config" gets a broken seed example.

The fix: Renumber to r2: m4, r3: m5, r3: m6 and remove the stray trailing quote.

8. Bare-metal prerequisites contradict the hardware page and bury a hard restriction (significant)

Location: https://docs.tigergraph.com/tigergraph-server/4.2/installation/bare-metal-install vs. https://docs.tigergraph.com/tigergraph-server/4.2/installation/hw-and-sw-requirements

Problem: Two distinct issues on the bare-metal prerequisites checklist:

1. "All provisioned machines must have enough disk space available (≥ 50 GB) for TigerGraph Cluster installation." — a 50 GB minimum that conflicts with the dedicated hardware sizing table on the same product's hw-and-sw-requirements page (which prescribes much larger working storage for any non-trivial workload). The two pages don't link to each other.
2. "All provisioned machines must be serving only TigerGraph." — a hard restriction (no co-tenancy with any other service on the host) that appears as one bullet in a long list and is not surfaced on the hardware-and-software requirements page at all.

Consequence: Someone following the bare-metal install guide can provision 50 GB nodes "passing prerequisites," and then run out of disk under real data. Worse, they can also try to share a node with an existing service, fail or destabilize the install, and find out only post-mortem that the docs forbade it.

The fix: Cross-link the bare-metal prerequisites page to the hardware-sizing page and quote the real working-storage minima. Promote the "serving only TigerGraph" restriction to the hardware page, in bold, alongside the OS table — it's a deployment-blocking constraint and belongs above the fold.

9. REST API docs reference a retired product brand and contradict their own auth list (significant)

Location: https://docs.tigergraph.com/tigergraph-server/4.2/API/

Problem: Two distinct bugs on one page:

1. "For self-installed systems, send requests to the NGINX proxy server (port 14240). For TigerGraph Cloud users, send requests to port 443." — "TigerGraph Cloud" is the retired brand; the current product is TigerGraph Savanna everywhere else in the docs.
2. "User credentials can be provided in 3 ways:" followed by four bullets (-u <user:password>, Authorization: Bearer <JWT-token>, Authorization: Basic <encoded-username-password>, Authorization: GSQL-Secret <gsql-secret>).

Consequence: Developers writing a TigerGraph client will trust a count that doesn't match the bullets and a hostname instruction tied to a defunct brand. Agents will lift either the wrong product name or the wrong auth count into generated code/answers.

The fix: Replace "TigerGraph Cloud" with "TigerGraph Savanna" (or both, with the historical name flagged as a redirect). Change "3 ways" → "4 ways" and verify by row count.

10. Savanna REST API surface is preview-only with no inline contract (critical)

Location: https://docs.tigergraph.com/savanna/main/rest-api/ and https://docs.tigergraph.com/savanna/main/workgroup-workspace/workspaces/connect-via-api

Problem: The Savanna REST API landing page is three sentences and an explicit "currently in preview" disclaimer — no endpoint list, no auth example, no sample request. The "Connect via APIs" page that should fill the gap documents only a UI-driven flow ("Click on Connect From API option in the Connect menu") with no programmable contract. Its "Limitations" section then says the generated code "does not support the database secret. If you need to connect using the database secret, please refer to Required Privilege" — implying the documented happy path can't actually do auth that other pages assume is GA.

Consequence: For a managed cloud product whose value proposition is programmatic access, the docs make programmatic access undocumented. Agents and developers have to click through a UI to generate snippets they could otherwise be told about in two paragraphs.

The fix: Publish at least an OpenAPI spec and a quickstart curl example with token auth on the REST API page. Document the database-secret auth flow inline rather than punting to a "Required Privilege" page. Move out of "Preview" or set a target GA date.

11. Editions comparison table makes a load-bearing compliance claim and breaks its own rendering (significant)

Location: https://docs.tigergraph.com/tigergraph-server/4.2/intro/comparison-of-editions

Problem: Three concrete defects on one page:

1. Audited Compliance row says Savanna is "SOC 2 Type 2" and TigerGraph DB is "PCI-DSS." No other docs page substantiates a PCI-DSS certification for the on-prem DB or links to an attestation.
2. Cross-Region Replication is "Coming soon" for Savanna in this table, but listed as supported (✅) for TigerGraph DB on the same row — with no note about how CRR works across the two editions.
3. The "Included" cell uses literal * characters mid-cell where the table column wants line breaks — rendering as "Fully-Managed Cloud-Native Service * Security * Separation of Storage and Compute * Unlimited Scale out * Solution Kits". The Security row also has a leading-asterisk bullet ("*Identity Provider (PDP) integration with SSO") that escapes the table cell.

Consequence: Procurement and security teams making purchase decisions rely on this table. An unsupported PCI-DSS claim is a real liability. The rendering bug makes the differentiator cell look like syntax garbage on the page where customers are deciding between editions.

The fix: Confirm and date each compliance certification with a link to the corresponding audit attestation page (or remove unverifiable claims). Reconcile CRR status between Savanna and DB editions. Fix the cell rendering by replacing * separators with proper markdown line breaks.

12. METRIC = "L2" is documented as Manhattan in one table and Euclidean in another, on the same page (critical)

Location: https://docs.tigergraph.com/gsql-ref/4.2/vector/

Problem: Two contradictions on the canonical vector reference page:

1. The "Vector Data and Search Specifications" table correctly lists "L2 (Euclidean)" as a similarity metric. The "Creating a Vector Schema" parameter table on the same page says "L2" means Manhattan — which is L1, not L2. Cosine, L2, and IP have unambiguous mathematical meanings.
2. The same parameter table caps DIMENSION at INT from 1 to 4096, but the spec table just above says max dimensions are 4096 for Community Edition and 32768 for Enterprise Edition. The parameter row gives no edition context.

Consequence: A developer wiring up vector search will either pick the wrong distance metric for their use case (ANN recall, retrieval quality, and any benchmark numbers will all be wrong) or, if they're on Enterprise, silently cap themselves at 4096-dimensional vectors because the parameter table told them to. For an agent generating CREATE VECTOR ATTRIBUTE DDL, both rows look authoritative.

The fix: Change the parameter table to read "L2" (Euclidean) and split the DIMENSION row into Community/Enterprise rows (or footnote it). Add a brief table mapping each metric string to its precise formula so this can't drift again.

13. GSQL 101 redirects new users off-site and references the previous major version (significant)

Location: https://docs.tigergraph.com/gsql-ref/4.2/tutorials/gsql-101/

Problem: The very first line of the entry-point tutorial under the 4.2 docs is: "Please see our newer GSQL tutorial at https://github.com/tigergraph/ecosys/blob/master/demos/guru_scripts/docker/tutorial/4.x/README.md". A few sections later the tutorial tells Docker users their files "can be found in /home/tigergraph/tutorial/3.x/gsql101/" — i.e. the 3.x path under the 4.2 docs. The Cloud-vs-Savanna naming inconsistency reappears here too: "If you want to use a TigerGraph Cloud solution for this tutorial, it needs to be a paid solution so that you have GSQL access."

Consequence: The official onboarding tutorial actively pushes users off to a GitHub README. Those who stay are told to look at a 3.x path on a 4.x install. This is the page Google ranks for "GSQL tutorial" — it's the first thing many evaluators see.

The fix: Either deprecate the on-docs GSQL 101 (and redirect cleanly) or fold the GitHub tutorial back in. Update the Docker example path to 4.x. Rename "TigerGraph Cloud" → "TigerGraph Savanna" throughout.

14. pyTigerGraph docs ship as 1.8 but lag the client's actual capabilities (critical)

Location: https://docs.tigergraph.com/pytigergraph/1.8/intro/, https://docs.tigergraph.com/pytigergraph/1.8/getting-started/install vs. https://github.com/tigergraph/pyTigerGraph

Problem: The current alias on docs.tigergraph.com resolves to pyTigerGraph 1.8 (released November 2024). The GitHub README — which the docs themselves link to — documents three capabilities entirely absent from the hosted docs:

• AsyncTigerGraphConnection (async/await client using aiohttp)
• pyTigerGraph[fast] (orjson backend, 2–10× faster JSON parsing)
• pyTigerGraph[mcp] (Model Context Protocol server, pyTigerGraph-mcp, with explicit migration instructions from pyTigerGraph.mcp → tigergraph_mcp)

The docs install page lists only pyTigerGraph and pyTigerGraph[gds], and the prerequisites say "Python 3.0 or higher" — a meaningless lower bound (Python 3.0 is from 2008 and can't run modern dependencies).

Consequence: Anyone using docs.tigergraph.com/pytigergraph/current as the source of truth — including every AI agent that follows the README's own link — will never know async, MCP, or the fast JSON backend exist. The MCP gap is especially painful: it's exactly the feature an AI agent would want, and the agents are the readers least likely to fall back to GitHub.

The fix: Cut a new pyTigerGraph docs release matching the shipping client (or update 1.8 in place). Document the gds/mcp/fast extras, AsyncTigerGraphConnection, the MCP server migration, and the real Python minimum version. Update the current alias.

15. pyTigerGraph "Getting Started" landing page has duplicated, content-free body (significant)

Location: https://docs.tigergraph.com/pytigergraph/1.8/getting-started/

Problem: The entire body of the page is:

"The Getting Started sequence walks you through the following: At the conclusion of the Getting Started sequence, you'll have reached an excellent starting point for further, more detail-driven activities."

…repeated twice, verbatim, with no list of what the sequence actually walks you through and no links to next pages.

Consequence: The page that should be the index for "how do I get started with the Python client" is a placeholder. Visitors have no next click; agents extracting "getting started steps for pyTigerGraph" get nothing usable.

The fix: Replace with a real index: a numbered list of steps (Install → Connect → First query → GDS), each linking to the corresponding sub-page, and a 5-line working hello-world snippet.

16. Upgrade page has an empty "Known Issue" heading and contradicts the install-user convention (significant)

Location: https://docs.tigergraph.com/tigergraph-server/4.2/installation/upgrade

Problem: Three concrete defects:

1. "Known Issue - File Permissions" appears as a heading with no body — only the word "The" remains before the next section starts.
2. The "Upgrading from v3.x" example uses /home/graphsql/tigergraph/app/3.10.0 as the AppRoot, while the rest of the docs use tigergraph as the install user (e.g. /home/tigergraph/tigergraph/app/...).
3. "Upgrading the Developer Edition or migrating to another edition are not supported." — but the editions comparison page lists Savanna, TigerGraph DB, and Community Edition only. There is no "Developer Edition" anywhere else in the current docs.

Consequence: Operators preparing a production upgrade get a heading-shaped warning with no warning text, a copy-pasteable command with the wrong user, and a restriction on an edition that doesn't appear in the catalog. All three risk an aborted or partial upgrade.

The fix: Either write the missing "File Permissions" section or remove the heading. Normalize the install user to tigergraph (or document both legacy graphsql and current tigergraph explicitly). Either re-introduce "Developer Edition" in the editions doc or remove the restriction.

17. Savanna release notes substitute generic strings for changelog entries and duplicate month headings (minor)

Location: https://docs.tigergraph.com/savanna/main/overview/release-notes

Problem: Multiple Savanna release entries describe shipped changes only as: "Fixed issues with query & developer experience", "Fixed UI and usability issues", "Fixed platform stability & reliability issues", "Improved stability and performance.", "Bug fixes." The heading ## Sep 2025 appears twice (for 2025-09-23 and 2025-09-19) rather than the entries nesting under one month. Bonus typo from earlier in the page: "Obvervability Enhancements" in July 2024.

Consequence: Savanna users can't tell whether a bug they hit was fixed in a given release, and agents asked "what did Savanna ship in Feb 2026?" get tautologies. Duplicate month headings break the page's TOC.

The fix: Require each release entry to name the change (issue ID, area, or short symptom). Collapse duplicate-month headings into one ## Sep 2025 with two dated subsections. Fix the "Obvervability" typo.

18. GSQL reference example uses an impossible calendar day (minor)

Location: https://docs.tigergraph.com/gsql-ref/4.2/querying/declaration-and-assignment-statements

Problem: The "base type variable" example on the central declarations-and-assignment page declares INT year = 2020, month = 12, day = 115;. day = 115 is not a valid calendar day. The example purports to show variable declaration; using a nonsense value undermines its didactic value (and any reader who tries to extend the example by passing day into a date function gets a runtime headache).

Consequence: This is a central reference example agents and humans alike will paste into GSQL queries. The value won't break compilation, but it leaks a "no one is reading this page" signal that erodes trust in the rest of the GSQL reference.

The fix: Set day = 31 (or any valid day-of-month) so the example reads as something a developer would actually write.

What they do well

• Vector + graph coverage is reasonably deep — the GSQL vector page enumerates supported metrics, ANN algorithms, indexing model, and limitations, which is more than most graph DBs document.
• Editions are at least matrixed — a single comparison table between Savanna / DB / Community Edition exists, which most multi-edition products lack.
• Release notes mostly exist — for an enterprise-y database with multiple LTS branches, both the 4.2 LTS and Savanna release notes pages are at least present (even if their quality varies — see issues 5 and 17).

Top 3 recommendations

1. Unify product naming and version timelines. Rename every "TigerGraph Cloud" reference to "Savanna" across the REST API intro, GSQL 101, and Savanna landing pages; fix the impossible "4.1.4 released May 2026 / 4.2.2 released Sep 2025" ordering on the docs home; group releases by LTS branch with an explicit "current" tag.
2. Close the pyTigerGraph code/docs gap. Ship a docs release that documents AsyncTigerGraphConnection, the [fast] and [mcp] extras, and the pyTigerGraph.mcp → tigergraph_mcp migration. Update the current alias.
3. Make the reference materials lintable. Add CI checks for: empty headings (issue 16), "TBD" in shipped-version known-issues tables (issue 5), bullet/list-count mismatches (issue 9), contradictions between same-page tables (issue 12), and bare-text labels in landing-page navigation grids (issues 3 and 4). Publish llms.txt + OpenAPI for Savanna so agents can index the result.