# Table ## *class* Table Tables are the fundamental data-containing entity in Redivis. Tables belong to either a dataset or workflow, and are made up of rows and variables (columns). Various methods allow you to read table data, as well as to create / update / delete tables belonging to an unreleased version of a dataset. Certain tables may be [file index tables](https://docs.redivis.com/reference/datasets/files#folders-and-index-tables), which represent a collection of non-tabular files, where each row corresponds to a file. There are additional methods available on file index tables that allow for you to interface with these files. ## Constructors
MethodDescription
redivis.table(name)Return a Table within the current default scope (either a dataset or workflow). In a Redivis notebook, the default scope will always be the notebook's workflow. If no default scope is specified, the table_reference must be fully qualified (see below).

table_reference is a string that identifies the unique table. In some cases this may be the table name, though in others you'll want to include additional information to identify the table and to ensure reproducibility if the table name changes. Consult the referencing resources documentation to learn more.

If you are operating within a Redivis notebook, you can specify "_source_" as the table reference to automatically refer to the notebook's source table.
Dataset.table(name)Return a Table within a specific dataset. The table_reference does not need to be fully qualified, since the table lookup is already scoped to a dataset.

Consult the referencing resources documentation to learn more.
Workflow.table(name)Return a Table within a specific workflow. The table_reference does not need to be fully qualified, since the table lookup is already scoped to a workflow.
Dataset.list_tables()Returns a list of Tables within a dataset
Workflow.list_tables()Returns a list of Tables within a workflow
## Examples {% tabs %} {% tab title="Basics" %} ```python table = redivis.table("Demo.iris_species.Iris") # owner.dataset|worfklow.table table.exists() # -> True table.get() # table.properties is now populated with the table resource definition table.variable("SepalLengthCm") # -> Returns a variable reference table.to_pandas_dataframe() # -> Returns a pandas dataframe for the table table.file("filename.png") # -> Return a reference to a file in a file index table ``` {% endtab %} {% tab title="Read tabular data" %} ```python # Can also do: redivis.table("Demo.iris_species.iris") dataset = redivis.organization("Demo").dataset("iris_species") table = dataset.table("Iris") table.to_pandas_dataframe() # Id SepalLengthCm SepalWidthCm PetalLengthCm PetalWidthCm Species # 0 33 5.2 4.1 1.5 0.1 Iris-setosa # ... # Other methods to read data: # table.to_arrow_batch_iterator() # table.to_arrow_dataset() # table.to_arrow_table() # table.to_geopandas_dataframe() # table.to_dask_dataframe() # table.to_polars_lazyframe() ``` {% endtab %} {% tab title="Read files" %} ```python import redivis from io import TextIOWrapper from PIL import Image # See https://redivis.com/datasets/yz1s-d09009dbb/files for example data table = redivis.table("demo.example_data_files:yz1s:v1_3.example_file_types:4c10") text_file = table.file("pandas_core.py") image_file = table.file("bogota.tiff"") ## Read file contents str = text_file.read(as_text=True) bytes = image_file.read() ## Open the file, as if it was on the filesystem with file.open() as f: f.read(100) # read 100 bytes with TextIOWrapper(file.open()) as f: f.readline() # read first line Image.open(table.file("bogota.tiff")) # PIL will automatically call open() on the file ## Download the file image_file.download("./path") # will be downloaded as ./path/bogota.tiff text_file.download("./path/renamed.txt") # will be downloaded as ./path/renamed.txt ``` {% endtab %} {% tab title="Create a table" %} 
dataset = redivis.user("user_or_organization_name").dataset("my dataset")

# Tables can only be created on an unreleased version. 
# If necessary, create a new version:
# dataset = dataset.create_next_version()

dataset.table("my_new_table").create(description="some description")

# Learn more about uploading data in the Upload documentation
upload = table.upload('data.csv').create('/path/to/file')
{% endtab %} {% tab title="List variables" %} ```python dataset = redivis.organization("Demo").dataset("iris_species") table = dataset.table("Iris") variables = table.list_variables() for variable in variables: print(variable.properties) ``` {% endtab %} {% endtabs %} ## Attributes
NameDescription
datasetA reference to the Dataset instance that constructed this table. Will be None if the table belongs to a workflow.
workflowA reference to the Workflow instance that constructed this table. Will be None if the table belongs to a dataset.
propertiesA dict containing the API resource representation of the table. This will only be populated after certain methods are called, particularly the get method, and will otherwise be None.
qualified_reference

The fully qualified reference to this table, for use (e.g.) in a SQL query.

For example,

demo.reddit:prpw:v1_0.posts:7q4m
scoped_referenceThe canonical reference for the table, without any qualifiers. E.g., posts:7q4m
## Methods
Reading data and metadata
Table.download([path, *, format, ...])Export a table in a particular format and download it to disk.
Table.exists()Check whether the table exists
Table.file(name, *, [...])Reference a File within a file index table.
Table.get()Fetch table metadata. Once called, the properties attribute on the table will be fully populated.
Table.list_files([max_results, *, ...])Return a list of File instances in a file index table.
Table.list_variables([max_results])Return a list of Variable instances associated with this table.
Table.to_arrow_batch_iterator([...])Return an iterator that yields pyarrow.RecordBatches, for processing the table's data in a memory-efficient streaming manner.
Table.to_arrow_dataset([max_results, ...])Return a pyarrow.dataset.Dataset for the table. Data is backed by disk, allowing for larger-than-memory analysis.
Table.to_arrow_table([max_results, ...])Return a pyarrow.Table with the table's data.
Table.to_geopandas_dataframe([...])Return a geopandas.GeoDataframe. For working with tables that contain a geography variable.
Table.to_dask_dataframe([max_results, ...])Return a dask.DataFrame. Data is backed by disk, allowing for larger-than-memory analysis.
Table.to_directory([max_results, ...])Create a virtual Directory based off a file index table.
Table.to_pandas_dataframe([max_results, ...])Return a pandas.DataFrame with the table's data.
Table.to_polars_lazyframe([max_results, ...])Return a polars.LazyFrame. Data is backed by disk, allowing for larger-than-memory analysis.
Table.to_read_streams([target_count, ...])Return a list of ReadStreams for parallel processing.
Table.to_sas(name, [max_results, ...])Load data into the current SAS session. Typically only used within a SAS Redivis notebook.
Table.to_stata([max_results, ...])Load data into the current Stata session. Typically only used within a Stata Redivis notebook.
Table.update_variables(variables)Batch update variable metadata on a table.
Table.variable(name)Reference a Variable within the table.
Uploading and modifying data
Table.add_files(*, [files, directory])Upload non-tabular files to an unreleased file index table.
Table.create([description, ...])Create a table within a dataset if it doesn't already exist. Table must belong to an unreleased version of the dataset.
Table.delete()Delete a table belonging to an unreleased version of a dataset.
Table.list_uploads([max_results])Return a list of uploads on a table
Table.update()Update properties on the table (name, description).
Table.upload()Create a reference to an Upload on the table, which can subsequently be used to upload tabular data.