From 6b8d1ad33cec060b2e8bf3bd4f3d943e0cfdfa79 Mon Sep 17 00:00:00 2001 From: Marcelo Soares Date: Thu, 16 Jul 2026 00:30:30 -0300 Subject: [PATCH 1/2] docs: Show vector values as Dart iterables --- .../03-vector-and-geography-fields.md | 39 +++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/docs/06-concepts/03-data-and-the-database/01-models/03-vector-and-geography-fields.md b/docs/06-concepts/03-data-and-the-database/01-models/03-vector-and-geography-fields.md index f6b4b2df..6ece5087 100644 --- a/docs/06-concepts/03-data-and-the-database/01-models/03-vector-and-geography-fields.md +++ b/docs/06-concepts/03-data-and-the-database/01-models/03-vector-and-geography-fields.md @@ -81,6 +81,45 @@ fields: hash: Bit(256) ``` +### Read vector values in Dart + +`Vector`, `HalfVector`, `SparseVector`, and `Bit` are Dart `Iterable` values. You can read their length, access a zero-based index with `[]`, loop over their elements, and use standard iterable methods: + +```dart +var embedding = const Vector([0.2, 0.4, 0.6]); + +print(embedding.length); // 3 +print(embedding[1]); // 0.4 + +for (var value in embedding) { + print(value); +} + +var hasLargeValue = embedding.any((value) => value > 0.5); +var doubled = embedding.map((value) => value * 2).toList(); +var values = embedding.toList(); +``` + +`Vector`, `HalfVector`, and `SparseVector` iterate over `double` values. `Bit` iterates over `bool` values: + +```dart +var flags = Bit([true, false, true]); +var enabledCount = flags.where((value) => value).length; +var secondFlag = flags[1]; // false +``` + +A `SparseVector` iterates over every dimension, including dimensions that are not stored internally. Indexed access and `toList()` return `0.0` for those dimensions: + +```dart +var sparse = SparseVector([1.5, 0.0, 0.0, 2.5]); + +print(sparse.length); // 4 +print(sparse[1]); // 0.0 +print(sparse.toList()); // [1.5, 0.0, 0.0, 2.5] +``` + +Accessing an index outside `0` through `length - 1` throws a `RangeError` for every vector type. + ## Geography fields Geography types are used for storing geospatial data on the surface of the Earth. They are stored as PostGIS geography columns in PostgreSQL using the WGS 84 coordinate system (SRID 4326), which is the standard used by GPS. The SRID is fixed to `4326`, available in Dart as `Geography.defaultSrid`; configuring a different SRID per column is not yet supported. From 864888dd6dad814ff72d24d0b233a63673319ae3 Mon Sep 17 00:00:00 2001 From: Marcelo Soares Date: Tue, 21 Jul 2026 15:29:14 -0300 Subject: [PATCH 2/2] docs: Align vector iterable section with the page style Avoid opening sentences with code spans, drop the RangeError note that restates standard Dart indexing behavior, and keep the constructor calls consistent across the examples. --- .../03-vector-and-geography-fields.md | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/docs/06-concepts/03-data-and-the-database/01-models/03-vector-and-geography-fields.md b/docs/06-concepts/03-data-and-the-database/01-models/03-vector-and-geography-fields.md index 6ece5087..30cc1fae 100644 --- a/docs/06-concepts/03-data-and-the-database/01-models/03-vector-and-geography-fields.md +++ b/docs/06-concepts/03-data-and-the-database/01-models/03-vector-and-geography-fields.md @@ -81,12 +81,12 @@ fields: hash: Bit(256) ``` -### Read vector values in Dart +### Reading vector values in Dart -`Vector`, `HalfVector`, `SparseVector`, and `Bit` are Dart `Iterable` values. You can read their length, access a zero-based index with `[]`, loop over their elements, and use standard iterable methods: +All four vector types implement `Iterable` and support zero-based indexed access with `[]`. Values read from the database can therefore be inspected directly, without converting them to a list first. ```dart -var embedding = const Vector([0.2, 0.4, 0.6]); +var embedding = Vector([0.2, 0.4, 0.6]); print(embedding.length); // 3 print(embedding[1]); // 0.4 @@ -96,19 +96,19 @@ for (var value in embedding) { } var hasLargeValue = embedding.any((value) => value > 0.5); -var doubled = embedding.map((value) => value * 2).toList(); var values = embedding.toList(); ``` -`Vector`, `HalfVector`, and `SparseVector` iterate over `double` values. `Bit` iterates over `bool` values: +The `Vector`, `HalfVector`, and `SparseVector` types iterate over `double` values, while `Bit` iterates over `bool` values. ```dart var flags = Bit([true, false, true]); -var enabledCount = flags.where((value) => value).length; -var secondFlag = flags[1]; // false + +print(flags[1]); // false +print(flags.where((value) => value).length); // 2 ``` -A `SparseVector` iterates over every dimension, including dimensions that are not stored internally. Indexed access and `toList()` return `0.0` for those dimensions: +A `SparseVector` iterates over every dimension, including the zero dimensions it does not store internally. Indexed access and `toList()` return `0.0` for those dimensions. ```dart var sparse = SparseVector([1.5, 0.0, 0.0, 2.5]); @@ -118,8 +118,6 @@ print(sparse[1]); // 0.0 print(sparse.toList()); // [1.5, 0.0, 0.0, 2.5] ``` -Accessing an index outside `0` through `length - 1` throws a `RangeError` for every vector type. - ## Geography fields Geography types are used for storing geospatial data on the surface of the Earth. They are stored as PostGIS geography columns in PostgreSQL using the WGS 84 coordinate system (SRID 4326), which is the standard used by GPS. The SRID is fixed to `4326`, available in Dart as `Geography.defaultSrid`; configuring a different SRID per column is not yet supported.