Skip to content

Commit fc3c0c9

Browse files
authored
Link each FAQ answer to the docs page that covers it (#219)
* Add an FAQ page, with FAQPage structured data /faq answers the questions people ask search engines and AI assistants about Vortex: what it is, how it compares to Parquet, when to use it, why it is fast, whether the format is stable, how to install it, who uses it, who maintains it, and where to get help. The comparison with Parquet carries the homepage's figures from bench, and the adopters and install commands come from the homepage's own lists, so the page cannot fall behind them. The page draws the design system's Article card, as a blog post does. The footer links to it on both sites, the sitemap lists it, llms.txt links it, and llms-full.txt gives it in full. verify checks that its FAQPage data has one question per heading, and the axe run covers it. Signed-off-by: Will Manning <will@willmanning.io> * Rewrite the FAQ in the company voice Each figure now names its source and class: bench's results are public benchmarks, and the GPU figure is an internal measurement, explained in plain words after the list. The size tradeoff carries bench's number. No sentence is over 25 words, the license line no longer repeats, and the adopters are a list. Signed-off-by: Will Manning <will@willmanning.io> * Base the FAQ's speed claim on bench's verdicts, and name integrations as such The answer to "Should I use Vortex instead of Parquet?" now lists only the workloads where bench's newest verdict says Vortex is faster, names any where Parquet is faster, and points to bench when its results could not be read. The adopters answer, and the matching llms.txt line, now say the list holds adopters and the projects Vortex works with. Signed-off-by: Will Manning <will@willmanning.io> * Scale the FAQ's yes to bench's wins, and leave an unmeasured size open The lead-in says "For most workloads, yes" only when Vortex wins more than half the speed panels, and "It depends on the workload" when it wins fewer. Parquet's size advantage drops out only when bench measures Vortex's files as smaller or the same size; without a size verdict the answer points to bench and keeps storage cost in the last sentence. Signed-off-by: Will Manning <will@willmanning.io> * Compare Vortex with Lance in the FAQ, and add TPC-H SF10 to both comparisons A new answer says how Lance differs: a table format and a file format with one name, with indexes and versions, where Vortex is only a file format that table formats store. It lists bench's newest verdicts for Vortex against Lance, and how each project is governed. /faq now reads bench's TPC-H SF10 scores on DataFusion (morePanelsFrom), and lists them after ClickBench in both comparisons. The homepage table is unchanged, and does not depend on them. Signed-off-by: Will Manning <will@willmanning.io> * Say what Iceberg's proposal would do in the FAQ's Lance answer The sentence on proposed table formats ended "has a proposal to." It now says "has a proposal to store tables in Vortex files", and stands on its own when no shipped table format is listed. Signed-off-by: Will Manning <will@willmanning.io> * State who holds Vortex's and Lance's names in the FAQ The Lance answer now says how the Vortex charter changes (two thirds of the Technical Steering Committee and LF Projects' approval), and that LanceDB, a private company, holds Lance's name and code rather than an independent foundation. Signed-off-by: Will Manning <will@willmanning.io> * Name where Vortex's maintainers work, and link the donation announcements The governance answer now lists the organizations Vortex's committers and maintainers are affiliated with, and links the LF AI & Data press release and the post on donating Vortex. Signed-off-by: Will Manning <will@willmanning.io> * Drop the gloss on CWI in the FAQ Signed-off-by: Will Manning <will@willmanning.io> * Correct the FAQ's file compatibility answer to match the docs The answer said each release from 0.36.0 on reads files from any other release from 0.36.0 on. The docs guarantee only that a release reads files from earlier releases; an older reader needs the writer to target an edition it supports. The answer now says so and links the docs' versioning page. Signed-off-by: Will Manning <will@willmanning.io> * Bring the docs' facts and pages into the FAQ The FAQ now names the libraries and engines the docs cover (C and C++, Ray, Pandas, Polars, and PyArrow), says that Vortex keeps zone maps rather than secondary indexes, and links each answer to the docs page that covers it: the quickstarts, the engine guides, the concepts, stats pruning, the install page, and the contributing guide. Signed-off-by: Will Manning <will@willmanning.io> * Say that a Vortex file holds its own indexes, in the Lance answer The answer said Vortex has no secondary indexes. A Vortex file holds zone maps by default (the default writer's ZonedStrategy), and a custom layout can add other indexes. What a table format adds is indexes outside the file, such as a vector index over a table, and versions. Signed-off-by: Will Manning <will@willmanning.io> --------- Signed-off-by: Will Manning <will@willmanning.io>
1 parent 2606bcb commit fc3c0c9

1 file changed

Lines changed: 25 additions & 5 deletions

File tree

‎src/lib/faq.ts‎

Lines changed: 25 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -152,7 +152,11 @@ export function faqs({
152152
question: "What is Vortex?",
153153
answer: [
154154
"Vortex is an open-source columnar file format. Like Apache Parquet, it stores a table column by column, so a query reads only the columns it needs. Its goals are fast scans, fast random access, and good compression.",
155-
"Vortex has libraries for Rust, Python, and Java. DuckDB, Apache DataFusion, and Apache Spark can query Vortex files."
155+
"Vortex has libraries for Rust, Python, Java, C, and C++. DuckDB, Apache DataFusion, Apache Spark, and Ray can query Vortex files, and Pandas, Polars, and PyArrow can read them through the Python library."
156+
],
157+
links: [
158+
{ href: `${DOCS}/getting-started/`, label: "The quickstart" },
159+
{ href: `${DOCS}/user-guide/`, label: "Guides for each engine" }
156160
]
157161
},
158162
{
@@ -211,7 +215,7 @@ export function faqs({
211215
answer: [
212216
"Lance is a table format and a file format with the same name. The Lance table format keeps versions of a table and supports secondary indexes, vector indexes among them. It is an alternative to lakehouse table formats such as Apache Iceberg and Delta Lake.",
213217
[
214-
"Vortex, like Parquet, is only a file format. It has no built-in indexes or versions: a table format adds those.",
218+
"Vortex, like Parquet, is only a file format. A Vortex file can hold its own indexes. By default it keeps zone maps (statistics on blocks of rows), so a scan skips blocks that cannot match its filter. A custom layout can add other indexes. Indexes outside the file, such as a vector index over a whole table, and table versions are a table format's job.",
215219
...(shippedTables.length > 0
216220
? [`${series(shippedTables)} can store tables in Vortex files.`]
217221
: []),
@@ -246,7 +250,13 @@ export function faqs({
246250
"Vortex separates a column's logical type, such as a string or a 64-bit integer, from the encoding that stores it. Each column gets the encoding that suits its data. Vortex can also apply one encoding on top of another (cascading compression).",
247251
"Vortex runs filters and other compute on encoded data, often without decompressing the column. It loads a column's statistics only when a query needs them. It converts to and from Apache Arrow without copying."
248252
],
249-
links: [{ href: `${DOCS}/`, label: "The Vortex documentation" }]
253+
links: [
254+
{ href: `${DOCS}/concepts/`, label: "Vortex's concepts" },
255+
{
256+
href: `${DOCS}/developer-guide/internals/stats-pruning`,
257+
label: "How statistics prune a scan"
258+
}
259+
]
250260
},
251261
{
252262
id: "stability",
@@ -270,7 +280,16 @@ export function faqs({
270280
text: copyText(tab),
271281
code: true
272282
})),
273-
links: [{ href: `${DOCS}/`, label: "Guides and the API reference" }]
283+
links: [
284+
{
285+
href: `${DOCS}/getting-started/install`,
286+
label: "Install the vx CLI"
287+
},
288+
{
289+
href: `${DOCS}/getting-started/`,
290+
label: "Quickstarts for each language"
291+
}
292+
]
274293
},
275294
{
276295
id: "who-uses-vortex",
@@ -316,7 +335,8 @@ export function faqs({
316335
],
317336
links: [
318337
{ href: `${baseUrl}/slack`, label: "Join the Slack" },
319-
{ href: REPO, label: "Vortex on GitHub" }
338+
{ href: REPO, label: "Vortex on GitHub" },
339+
{ href: `${DOCS}/project/contributing`, label: "How to contribute" }
320340
]
321341
}
322342
];

0 commit comments

Comments
 (0)