|
19 | 19 |
|
20 | 20 | package org.apache.datafusion; |
21 | 21 |
|
| 22 | +import java.io.ByteArrayInputStream; |
| 23 | +import java.io.IOException; |
| 24 | +import java.nio.channels.Channels; |
| 25 | + |
22 | 26 | import org.apache.arrow.c.ArrowArrayStream; |
23 | 27 | import org.apache.arrow.c.Data; |
24 | 28 | import org.apache.arrow.memory.BufferAllocator; |
25 | 29 | import org.apache.arrow.vector.ipc.ArrowReader; |
| 30 | +import org.apache.arrow.vector.ipc.ReadChannel; |
| 31 | +import org.apache.arrow.vector.ipc.message.MessageSerializer; |
| 32 | +import org.apache.arrow.vector.types.pojo.Schema; |
26 | 33 |
|
27 | 34 | /** |
28 | 35 | * A lazy representation of a query plan, mirroring the Rust DataFusion {@code DataFrame}. Created |
@@ -170,6 +177,77 @@ private static long resolveTokenHandle(CancellationToken token) { |
170 | 177 | return handle; |
171 | 178 | } |
172 | 179 |
|
| 180 | + /** |
| 181 | + * Return the Arrow {@link Schema} of this DataFrame's output. Non-consuming: the receiver remains |
| 182 | + * usable and must still be closed independently. Schema inspection does not execute the plan. |
| 183 | + * |
| 184 | + * <p>The schema is transferred via Arrow IPC; no {@link BufferAllocator} is required because a |
| 185 | + * schema carries no buffer data. |
| 186 | + */ |
| 187 | + public Schema schema() { |
| 188 | + if (nativeHandle == 0) { |
| 189 | + throw new IllegalStateException("DataFrame is closed or already collected"); |
| 190 | + } |
| 191 | + byte[] ipcBytes = schemaIpc(nativeHandle); |
| 192 | + try { |
| 193 | + return MessageSerializer.deserializeSchema( |
| 194 | + new ReadChannel(Channels.newChannel(new ByteArrayInputStream(ipcBytes)))); |
| 195 | + } catch (IOException e) { |
| 196 | + throw new RuntimeException("Failed to deserialize IPC schema", e); |
| 197 | + } |
| 198 | + } |
| 199 | + |
| 200 | + /** |
| 201 | + * Return a new DataFrame whose rows describe the plan that would execute this DataFrame. |
| 202 | + * Non-consuming: the receiver remains usable and must still be closed independently. |
| 203 | + * |
| 204 | + * <p>With {@code verbose=false} and {@code analyze=false} (the cheap, lazy variant), the result |
| 205 | + * contains the logical plan only. {@code verbose=true} adds optimised-plan and physical-plan |
| 206 | + * rows; {@code analyze=true} runs the plan and attaches per-operator metrics. Render via {@link |
| 207 | + * #show()} or {@link #collect(BufferAllocator)}. |
| 208 | + */ |
| 209 | + public DataFrame explain(boolean verbose, boolean analyze) { |
| 210 | + if (nativeHandle == 0) { |
| 211 | + throw new IllegalStateException("DataFrame is closed or already collected"); |
| 212 | + } |
| 213 | + return new DataFrame(explainPlan(nativeHandle, verbose, analyze)); |
| 214 | + } |
| 215 | + |
| 216 | + /** |
| 217 | + * Materialise this DataFrame into an in-memory table and return a new DataFrame that scans it. |
| 218 | + * Non-consuming: the receiver remains usable and must still be closed independently. |
| 219 | + * |
| 220 | + * <p>Executes the plan eagerly: the entire result set is held in native memory until the returned |
| 221 | + * DataFrame is closed. Suitable for intermediate results that will be reused across multiple |
| 222 | + * downstream queries. |
| 223 | + * |
| 224 | + * @throws RuntimeException if execution fails. |
| 225 | + */ |
| 226 | + public DataFrame cache() { |
| 227 | + if (nativeHandle == 0) { |
| 228 | + throw new IllegalStateException("DataFrame is closed or already collected"); |
| 229 | + } |
| 230 | + return new DataFrame(cachePlan(nativeHandle)); |
| 231 | + } |
| 232 | + |
| 233 | + /** |
| 234 | + * Compute summary statistics (count, null_count, mean, std, min, max, median) over this |
| 235 | + * DataFrame's columns and return them as a new DataFrame. Non-consuming: the receiver remains |
| 236 | + * usable and must still be closed independently. |
| 237 | + * |
| 238 | + * <p>Executes the plan: DataFusion runs seven aggregate sub-plans against this DataFrame to build |
| 239 | + * the summary table. Numeric columns receive every statistic; non-numeric columns receive {@code |
| 240 | + * count} / {@code null_count} / {@code min} / {@code max} where applicable. |
| 241 | + * |
| 242 | + * @throws RuntimeException if execution fails. |
| 243 | + */ |
| 244 | + public DataFrame describe() { |
| 245 | + if (nativeHandle == 0) { |
| 246 | + throw new IllegalStateException("DataFrame is closed or already collected"); |
| 247 | + } |
| 248 | + return new DataFrame(describePlan(nativeHandle)); |
| 249 | + } |
| 250 | + |
173 | 251 | /** Execute the plan and return the number of rows. */ |
174 | 252 | public long count() { |
175 | 253 | if (nativeHandle == 0) { |
@@ -431,6 +509,14 @@ private static native void executeStreamDataFrame( |
431 | 509 |
|
432 | 510 | private static native long countRows(long handle); |
433 | 511 |
|
| 512 | + private static native byte[] schemaIpc(long handle); |
| 513 | + |
| 514 | + private static native long explainPlan(long handle, boolean verbose, boolean analyze); |
| 515 | + |
| 516 | + private static native long cachePlan(long handle); |
| 517 | + |
| 518 | + private static native long describePlan(long handle); |
| 519 | + |
434 | 520 | private static native void showDataFrame(long handle); |
435 | 521 |
|
436 | 522 | private static native void showDataFrameWithLimit(long handle, int limit); |
|
0 commit comments