Getting Started

The Oracle Cloud Infrastructure (OCI) Object Storage filesystem (ocifs) is an fsspec implementation for use with Object Storage.

Quickstart with Pandas

Begin by importing ocifs and pandas. When importing ocifs, you are registering the oci protocol with pandas:

import ocifs
import pandas as pd

Now that the oci protocol is registered with pandas, you can read and write from and to Object Storage as easily as you can locally. For example, you could read an Excel file, path/file.xls, from your bucket in a namespace easily using:

df = pd.read_excel("oci://bucket@namespace/path/file.xls",
                   storage_options={"config": "~/.oci/config"})

df.to_parquet("oci://bucket@namespace/path/file.parquet",
              storage_options={"config": "~/.oci/config"})

You could also use Dask:

from dask import dataframe as dd

ddf = dd.read_csv("oci://bucket@namespace/path/file*.csv",
                  storage_options={"config": "~/.oci/config"})

The storage_options parameter contains a dictionary of arguments that are passed to the underlying OCIFileSystem method. The following docstring lists the valid arguments to storage options:

Quickstart to UNIX Operations

You can interact with the filesytem directly using most UNIX commands like ls, cp, exists, mkdir, rm, walk, find, and so on.

Instantiate a filesystem from your configuration, see Getting Connected. Every filesystem instance operates within the home region of the configuration. The cp command is the only command that has cross-region support. You must create a unique filesystem instance for each region.

fs = ocifs.OCIFileSystem(config="~/.oci/config", profile="DEFAULT", default_block_size=5*2**20)

fs.ls("oci://bucket@namespace/path")
# []

fs.touch("oci://bucket@namespace/path/file.txt")

fs.exists("oci://bucket@namespace/path/file.txt")
# True

fs.cat("oci://bucket@namespace/path/file.txt")
# ""

fs.rm("oci://bucket@namespace", recursive=True)

fs.exists("oci://bucket@namespace/path/file.txt")
# False

Following are examples of how you can use the OCIFileSystem and OCIFile objects.