From 141d966548d5e0a6e0e4ebe798bbcfc16ead09e3 Mon Sep 17 00:00:00 2001
From: Nick Crews <nicholas.b.crews@gmail.com>
Date: Mon, 2 Oct 2023 11:00:53 -0800
Subject: [PATCH] docs: add basic intro docstring to Table class

This is such a central class that it should have a docstring.
---
 ibis/expr/types/relations.py | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/ibis/expr/types/relations.py b/ibis/expr/types/relations.py
index 5c97d979b228f..59487a995ba12 100644
--- a/ibis/expr/types/relations.py
+++ b/ibis/expr/types/relations.py
@@ -104,6 +104,39 @@ def f(  # noqa: D417
 
 @public
 class Table(Expr, _FixedTextJupyterMixin):
+    """An immutable and lazy dataframe.
+
+    Analogous to a SQL table or a pandas DataFrame. A table expression contains
+    an [ordered set of named columns](./schemas.qmd#ibis.expr.schema.Schema),
+    each with a single known type. Unless explicitly ordered with an
+    [`.order_by()`](#ibis.expr.types.relations.Table.order_by),
+    the order of rows is undefined.
+
+    By "immutable", we mean that a table expression cannot be modified: every
+    method on a Table returns a new Table with those changes. By "lazy", we
+    mean that a Table expression does not contain any actual data.
+    Instead, it is a symbolic expression that represents a set of operations
+    to be performed, which typically is translated into a SQL query. That
+    SQL query is then executed on a backend, where the data actually lives.
+    The result (now small enough to be manageable) can then be materialized back
+    into python as a pandas/pyarrow/python DataFrame/Column/scalar.
+
+    You will not create Table objects directly. Instead, you will create one
+
+    - from a pandas DataFrame, pyarrow table, Polars table, or raw python dicts/lists
+      with [`ibis.memtable(df)`](#ibis.memtable)
+    - from an existing table in a data platform with
+      [`connection.table("name")`](#ibis.backends.duckdb.Backend.table)
+    - from a file or URL, into a specific backend with
+      [`connection.read_csv/parsquet/json("path/to/file")`](../backends/duckdb.qmd#ibis.backends.duckdb.Backend.read_csv)
+      (only some backends, typically local ones, support this)
+    - from a file or URL, into the default backend with
+       [`ibis.read_csv/read_json/read_parquet("path/to/file")`](#ibis.read_csv)
+
+    See the [user guide](https://ibis-project.org/how-to/input-output/basics) for more
+    info.
+    """
+
     # Higher than numpy & dask objects
     __array_priority__ = 20