From e4946a503c1ec0460363c834e4e9c386c91ee98b Mon Sep 17 00:00:00 2001 From: Ib Green Date: Wed, 16 Oct 2024 22:35:30 -0400 Subject: [PATCH] docs: Initial v4.4 docs (#3120) --- docs/upgrade-guide.md | 25 +++++++++++++++++++++++++ docs/whats-new.mdx | 40 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 65 insertions(+) diff --git a/docs/upgrade-guide.md b/docs/upgrade-guide.md index 5e16cc6390..09db070166 100644 --- a/docs/upgrade-guide.md +++ b/docs/upgrade-guide.md @@ -1,5 +1,30 @@ # Upgrade Guide +## Upgrading to v5.0 (In development) + +loaders.gl v5 is a major re-imagination of the library the optimizes loaders.gl for big cloud-native, binary data. + +**Apache Arrow as the core format** + +- Most loaders now return binary data in the Apache Arrow format. +- This aligns with parallel efforts in companion libraries like deck.gl to work with zero-copy, compact binary data instead of bloated, deserialized javascript data structures. +- Binary columnar data can bring in an order of magnitude better memory usage and load/processing performance on big datasets. + +**Single output format per loader** + +- The `shape` option that was introduced in loaders.gl v3 to allow loaders to return different data formats is now deprecated and removed in many places. +- Instead, applications can use utilities in the `@loaders.gl/schema-utils` and `@loaders.gl/gis` modules to convert for Apache Arrow and Apache GeoArrow to more traditional (but less efficient) JavaScript formats. + +**Apache Arrow JS** + +- The Apache Arrow JS library is now a central dependency. +- This does add to the bundle size, especially for the script versions of the loaders where code reuse between bundles is harder. +- The Apache Arrow JS library is powerful but can be hard to work with as it can handle very complex binary data schemas. loaders.gl provides its own set of Apache Arrow docs and a suite of utility functions making it easier + +**Improved `DataSource` APIs** + +- The `Source` and `DataSource` APIs have matured leading to some minor breaking changes. + ## Upgrading to v4.3 (In development) **Breaking Changes** diff --git a/docs/whats-new.mdx b/docs/whats-new.mdx index 06a192d234..6fd9ca703f 100644 --- a/docs/whats-new.mdx +++ b/docs/whats-new.mdx @@ -1,5 +1,45 @@ # What's New +## v4.4 (in development) + +Target Release Date: Q1 2025 + +loaders.gl v4.4 will focus on cloud-native, binary data. +A number of modules will expose "ArrowLoaders" will return binary data in the Apache Arrow and Apache GeoArrow formats. + +While no loader support has been removed, the flavor of the loaders.gl framework is changing. + +**Apache Arrow as a core format** + - Many new loaders now return binary data in the Apache Arrow format. + - This aligns with parallel efforts in companion libraries like deck.gl (as well as the ecosystem at large) to work with zero-copy, compact binary data instead of bloated, deserialized javascript data structures. + - Binary columnar data brings in an order of magnitude better memory usage and improved load/processing performance on big datasets. + - The Apache Arrow JS library is now a central dependency of loaders.gl. + +**Improved `DataSource` APIs** + - The `Source` and `DataSource` APIs have matured and are now easier to work with. + - Consule the upgrade guide for migration details. + +**Single output format per loader** + - `.shape` is deprecated. + - This will simplify loader implementations. + - Applications benefit from more predictable return types for loaders. + - When needed, applications can now instead use utilities in the `@loaders.gl/schema-utils` and `@loaders.gl/gis` modules to convert Apache Arrow and Apache GeoArrow to more traditional (but less efficient) JavaScript formats. + +Per-module changes + +- **`@loaders.gl/csv`** + - `CSVArrowLoader` - New CSV loader that returns Apache Arrow tables. + +- **`@loaders.gl/parquet`** + - `ParquetArrowLoader` now returns Apache Arrow tables and leverages the high-performance `parquet-wasm` library. + - The v4 Parquet loader is still available as `ParquetJSONLoader` + +- **`@loaders.gl/schema-utils`** + - New module for working with and converting Apache Arrow data. + +- **`@loaders.gl/gis`** + - Now provides support for working Apache GeoArrow data. + ## v4.3 Release Date: October 16, 2024