This is an automated email from the ASF dual-hosted git repository.
raulcd pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/arrow.git
The following commit(s) were added to refs/heads/main by this push:
new 27fdd358b4 MINOR: [Docs] Clarify struct validity masking with 'hidden
data' example (#49554)
27fdd358b4 is described below
commit 27fdd358b428b3f0d152be250df027e520dc8142
Author: Philipp Ucke <[email protected]>
AuthorDate: Fri Mar 20 13:41:25 2026 +0100
MINOR: [Docs] Clarify struct validity masking with 'hidden data' example
(#49554)
### Rationale for this change
The current documentation contains a technical inconsistency in the
validity bitmap values for column 4.
According to the Arrow specification:
> In Arrow, a dedicated buffer, known as the validity (or “null”) bitmap,
is used alongside the data indicating whether each value in the array is null
or not: a value of 1 means that the value is not-null (“valid”), whereas a
value of 0 indicates that the value is null.
In the existing example, the validity bitmap for the third row of the
variable-size binary child array is incorrectly set to 1, despite the row being
null. This PR corrects that bit to 0 to align with the fixed-size primitive
child array and the overall Arrow memory layout standards.
### What changes are included in this PR?
Updated the struct-diagram.svg
### Are these changes tested?
No
### Are there any user-facing changes?
No
Authored-by: Philipp Ucke <[email protected]>
Signed-off-by: Raúl Cumplido <[email protected]>
---
docs/source/format/Intro.rst | 7 +++++++
docs/source/format/images/struct-diagram.svg | 6 +++---
2 files changed, 10 insertions(+), 3 deletions(-)
diff --git a/docs/source/format/Intro.rst b/docs/source/format/Intro.rst
index ce35402bff..e98bd40e01 100644
--- a/docs/source/format/Intro.rst
+++ b/docs/source/format/Intro.rst
@@ -296,6 +296,13 @@ key is the field name and the child array its values. The
field (key) is
saved in the schema and the values of a specific field (key) are saved in
the child array.
+Since child arrays are independent, Arrow does not enforce physical
+consistency between the struct's validity bitmap and those of it's children.
+Logically, a struct row is only valid if both the parent and the child
+bitmaps have a value of 1 for that slot (a logical AND operation).
+This allows for "hidden" data to exist in child arrays at null struct
+positions (see ``alice`` below).
+
.. figure:: ./images/struct-diagram.svg
:alt: Diagram is showing the difference between the struct data type
presented in a Table and the data actually stored in computer
diff --git a/docs/source/format/images/struct-diagram.svg
b/docs/source/format/images/struct-diagram.svg
index 81ff29689a..17053414e0 100644
--- a/docs/source/format/images/struct-diagram.svg
+++ b/docs/source/format/images/struct-diagram.svg
@@ -1,6 +1,6 @@
<svg version="1.1" xmlns="http://www.w3.org/2000/svg"; viewBox="0 0
1495.3089493858786 991.8194870076786" width="1495.3089493858786"
height="991.8194870076786">
<!-- svg-source:excalidraw -->
-
+
<defs>
<style class="style-fonts">
@font-face {
@@ -16,6 +16,6 @@
src: url("https://excalidraw.com/Assistant-Regular.woff2";);
}
</style>
-
+
</defs>
- <g stroke-linecap="round" transform="translate(18.277819259969647 10)
rotate(0 733.5155650629545 29.721659908090714)"><path d="M-3.55 1.29 L1465.25
1.38 L1465.08 60.09 L1.55 57.91" stroke="none" stroke-width="0"
fill="#b2f2bb"></path><path d="M0.61 -0.33 C513.17 -8.83, 1026.67 -8.07,
1467.57 0.93 M-0.53 -0.4 C530.65 0.22, 1061.37 -0.37, 1467.57 0.51 M1469.88
3.47 C1469.48 11.73, 1466.32 32.23, 1468.13 62.18 M1465.16 -0.72 C1466.59
13.58, 1466.37 26.07, 1466.84 61.15 M1467.08 60.93 C100 [...]
\ No newline at end of file
+ <g stroke-linecap="round" transform="translate(18.277819259969647 10)
rotate(0 733.5155650629545 29.721659908090714)"><path d="M-3.55 1.29 L1465.25
1.38 L1465.08 60.09 L1.55 57.91" stroke="none" stroke-width="0"
fill="#b2f2bb"></path><path d="M0.61 -0.33 C513.17 -8.83, 1026.67 -8.07,
1467.57 0.93 M-0.53 -0.4 C530.65 0.22, 1061.37 -0.37, 1467.57 0.51 M1469.88
3.47 C1469.48 11.73, 1466.32 32.23, 1468.13 62.18 M1465.16 -0.72 C1466.59
13.58, 1466.37 26.07, 1466.84 61.15 M1467.08 60.93 C100 [...]
