|
| 1 | +# Licensed to the Apache Software Foundation (ASF) under one |
| 2 | +# or more contributor license agreements. See the NOTICE file |
| 3 | +# distributed with this work for additional information |
| 4 | +# regarding copyright ownership. The ASF licenses this file |
| 5 | +# to you under the Apache License, Version 2.0 (the |
| 6 | +# "License"); you may not use this file except in compliance |
| 7 | +# with the License. You may obtain a copy of the License at |
| 8 | +# |
| 9 | +# http://www.apache.org/licenses/LICENSE-2.0 |
| 10 | +# |
| 11 | +# Unless required by applicable law or agreed to in writing, |
| 12 | +# software distributed under the License is distributed on an |
| 13 | +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| 14 | +# KIND, either express or implied. See the License for the |
| 15 | +# specific language governing permissions and limitations |
| 16 | +# under the License. |
| 17 | + |
| 18 | +"""This module supports physical and logical plans in DataFusion.""" |
| 19 | + |
| 20 | +from __future__ import annotations |
| 21 | + |
| 22 | +import datafusion._internal as df_internal |
| 23 | + |
| 24 | +from typing import List, Any, TYPE_CHECKING |
| 25 | + |
| 26 | +if TYPE_CHECKING: |
| 27 | + from datafusion.context import SessionContext |
| 28 | + |
| 29 | +__all__ = [ |
| 30 | + "LogicalPlan", |
| 31 | + "ExecutionPlan", |
| 32 | +] |
| 33 | + |
| 34 | + |
| 35 | +class LogicalPlan: |
| 36 | + """Logical Plan. |
| 37 | +
|
| 38 | + A `LogicalPlan` is a node in a tree of relational operators (such as |
| 39 | + Projection or Filter). |
| 40 | +
|
| 41 | + Represents transforming an input relation (table) to an output relation |
| 42 | + (table) with a potentially different schema. Plans form a dataflow tree |
| 43 | + where data flows from leaves up to the root to produce the query result. |
| 44 | +
|
| 45 | + `LogicalPlan`s can be created by the SQL query planner, the DataFrame API, |
| 46 | + or programmatically (for example custom query languages). |
| 47 | + """ |
| 48 | + |
| 49 | + def __init__(self, plan: df_internal.LogicalPlan) -> None: |
| 50 | + """This constructor should not be called by the end user.""" |
| 51 | + self._raw_plan = plan |
| 52 | + |
| 53 | + def to_variant(self) -> Any: |
| 54 | + """Convert the logical plan into its specific variant.""" |
| 55 | + return self._raw_plan.to_variant() |
| 56 | + |
| 57 | + def inputs(self) -> List[LogicalPlan]: |
| 58 | + """Returns the list of inputs to the logical plan.""" |
| 59 | + return [LogicalPlan(p) for p in self._raw_plan.inputs()] |
| 60 | + |
| 61 | + def __repr__(self) -> str: |
| 62 | + """Generate a printable representation of the plan.""" |
| 63 | + return self._raw_plan.__repr__() |
| 64 | + |
| 65 | + def display(self) -> str: |
| 66 | + """Print the logical plan.""" |
| 67 | + return self._raw_plan.display() |
| 68 | + |
| 69 | + def display_indent(self) -> str: |
| 70 | + """Print an indented form of the logical plan.""" |
| 71 | + return self._raw_plan.display_indent() |
| 72 | + |
| 73 | + def display_indent_schema(self) -> str: |
| 74 | + """Print an indented form of the schema for the logical plan.""" |
| 75 | + return self._raw_plan.display_indent_schema() |
| 76 | + |
| 77 | + def display_graphviz(self) -> str: |
| 78 | + """Print the graph visualization of the logical plan. |
| 79 | +
|
| 80 | + Returns a `format`able structure that produces lines meant for graphical display |
| 81 | + using the `DOT` language. This format can be visualized using software from |
| 82 | + [`graphviz`](https://graphviz.org/) |
| 83 | + """ |
| 84 | + return self._raw_plan.display_graphviz() |
| 85 | + |
| 86 | + @staticmethod |
| 87 | + def from_proto(ctx: SessionContext, data: bytes) -> LogicalPlan: |
| 88 | + """Create a LogicalPlan from protobuf bytes. |
| 89 | +
|
| 90 | + Tables created in memory from record batches are currently not supported. |
| 91 | + """ |
| 92 | + return LogicalPlan(df_internal.LogicalPlan.from_proto(ctx.ctx, data)) |
| 93 | + |
| 94 | + def to_proto(self) -> bytes: |
| 95 | + """Convert a LogicalPlan to protobuf bytes. |
| 96 | +
|
| 97 | + Tables created in memory from record batches are currently not supported. |
| 98 | + """ |
| 99 | + return self._raw_plan.to_proto() |
| 100 | + |
| 101 | + |
| 102 | +class ExecutionPlan: |
| 103 | + """Represent nodes in the DataFusion Physical Plan.""" |
| 104 | + |
| 105 | + def __init__(self, plan: df_internal.ExecutionPlan) -> None: |
| 106 | + """This constructor should not be called by the end user.""" |
| 107 | + self._raw_plan = plan |
| 108 | + |
| 109 | + def children(self) -> List[ExecutionPlan]: |
| 110 | + """Get a list of children `ExecutionPlan`s that act as inputs to this plan. |
| 111 | +
|
| 112 | + The returned list will be empty for leaf nodes such as scans, will contain a |
| 113 | + single value for unary nodes, or two values for binary nodes (such as joins). |
| 114 | + """ |
| 115 | + return [ExecutionPlan(e) for e in self._raw_plan.children()] |
| 116 | + |
| 117 | + def display(self) -> str: |
| 118 | + """Print the physical plan.""" |
| 119 | + return self._raw_plan.display() |
| 120 | + |
| 121 | + def display_indent(self) -> str: |
| 122 | + """Print an indented form of the physical plan.""" |
| 123 | + return self._raw_plan.display_indent() |
| 124 | + |
| 125 | + def __repr__(self) -> str: |
| 126 | + """Print a string representation of the physical plan.""" |
| 127 | + return self._raw_plan.__repr__() |
| 128 | + |
| 129 | + @property |
| 130 | + def partition_count(self) -> int: |
| 131 | + """Returns the number of partitions in the physical plan.""" |
| 132 | + return self._raw_plan.partition_count |
| 133 | + |
| 134 | + @staticmethod |
| 135 | + def from_proto(ctx: SessionContext, data: bytes) -> ExecutionPlan: |
| 136 | + """Create an ExecutionPlan from protobuf bytes. |
| 137 | +
|
| 138 | + Tables created in memory from record batches are currently not supported. |
| 139 | + """ |
| 140 | + return ExecutionPlan(df_internal.ExecutionPlan.from_proto(ctx.ctx, data)) |
| 141 | + |
| 142 | + def to_proto(self) -> bytes: |
| 143 | + """Convert an ExecutionPlan into protobuf bytes. |
| 144 | +
|
| 145 | + Tables created in memory from record batches are currently not supported. |
| 146 | + """ |
| 147 | + return self._raw_plan.to_proto() |
0 commit comments