Learn how to load and export DataFrames as JSON, Excel, and Parquet files in GPandas. JSON is read and written in records orientation; Excel support is powered by excelize and Parquet by parquet-go.

 

Overview

FormatReadWrite
JSONRead_json()ToJSON()
Excel (.xlsx)Read_excel()ToExcel()
ParquetRead_parquet()ToParquet()

 

 

Read_json

Reads a JSON file in records orientation (a top-level array of objects) into a DataFrame.

 

Function Signature 

func (GoPandas) Read_json(filepath string) (*dataframe.DataFrame, error)

 

Behaviour

  • Each object becomes a row.
  • The union of all keys becomes the columns, sorted alphabetically.
  • Missing keys in a record produce null values.
  • JSON numbers decode as float64.

 

Example

Given data.json:

[{"name":"Alice","age":30},{"name":"Bob","age":25}]
gp := gpandas.GoPandas{}
df, err := gp.Read_json("data.json")
if err != nil {
    log.Fatalf("Read_json failed: %v", err)
}
fmt.Println(df.DTypes())
map[age:float64 name:string]

Columns are sorted (age, then name), and age is float64 because JSON numbers decode as floats. Convert with AsType if you need integers.

 

 

ToJSON

Serializes the DataFrame to JSON in records orientation. Column order is preserved within each object, and null values are emitted as JSON null.

 

Function Signature 

func (df *DataFrame) ToJSON(filepath string) (string, error)

If filepath is empty, the JSON string is returned; otherwise it is written to the file and ("", nil) is returned.

 

Example 

// Return as a string
s, err := df.ToJSON("")
if err != nil {
    log.Fatalf("ToJSON failed: %v", err)
}
fmt.Println(s)

// Or write to a file
_, err = df.ToJSON("out.json")

 

Output 

[{"Department":"Eng","Salary_sum":450,"Salary_mean":150,"Salary_max":200,"Units_sum":9},{"Department":"Sales","Salary_sum":120,"Salary_mean":60,"Salary_max":70,"Units_sum":13}]

 

 

Read_excel

Reads an Excel .xlsx file into a DataFrame. The first row is treated as the header, and all remaining cells are loaded as strings (like Read_csv).

 

Function Signature 

func (GoPandas) Read_excel(filepath string, sheet ...string) (*dataframe.DataFrame, error)

If a sheet name is omitted, the first sheet is used.

 

Example 

gp := gpandas.GoPandas{}

df, err := gp.Read_excel("data.xlsx")
if err != nil {
    log.Fatalf("Read_excel failed: %v", err)
}

// Cells load as strings; convert numeric columns as needed
df, _ = df.AsType("Age", dataframe.IntCol{})
fmt.Println(df.String())

 

 

ToExcel

Writes the DataFrame to an Excel .xlsx file with the column headers in the first row, followed by one row per record. Null values are written as empty cells.

 

Function Signature 

func (df *DataFrame) ToExcel(filepath string, sheet ...string) error

The sheet name defaults to "Sheet1".

 

Example 

if err := df.ToExcel("out.xlsx"); err != nil {
    log.Fatalf("ToExcel failed: %v", err)
}

// Custom sheet name
err := df.ToExcel("out.xlsx", "Employees")

 

I/O Flow 

flowchart LR
    subgraph Sources["Files"]
        J[data.json]
        X[data.xlsx]
    end

    subgraph DF["DataFrame"]
        D[Columns + Index]
    end

    subgraph Out["Exports"]
        OJ[out.json]
        OX[out.xlsx]
    end

    J -->|Read_json| D
    X -->|Read_excel| D
    D -->|ToJSON| OJ
    D -->|ToExcel| OX

    style Sources fill:#1e293b,stroke:#3b82f6,stroke-width:2px
    style DF fill:#1e293b,stroke:#f59e0b,stroke-width:2px
    style Out fill:#1e293b,stroke:#22c55e,stroke-width:2px

 

 

Read_parquet

Reads a Parquet file into a DataFrame. Column types are inferred from the Parquet schema: INT64 → int64, DOUBLE/FLOAT → float64, BOOLEAN → bool, and BYTE_ARRAY → string.

 

Function Signature 

func (GoPandas) Read_parquet(filepath string) (*dataframe.DataFrame, error)

Note: Columns are read back in the order stored in the Parquet schema (alphabetical).

 

ToParquet

Writes the DataFrame to a Parquet file. Columns are mapped to Parquet types: float64 → DOUBLE, int64 → INT64, bool → BOOLEAN, and everything else (string, datetime, categorical) → UTF8 string.

 

Function Signature 

func (df *DataFrame) ToParquet(filepath string) error

Note: Parquet columns are written as required (non-nullable). Null values are written as the zero value for the column type (0, 0.0, "", false).

 

Example 

gp := gpandas.GoPandas{}

// Write
if err := df.ToParquet("data.parquet"); err != nil {
    log.Fatalf("ToParquet failed: %v", err)
}

// Read back
loaded, err := gp.Read_parquet("data.parquet")
if err != nil {
    log.Fatalf("Read_parquet failed: %v", err)
}
fmt.Println(loaded.DTypes())

 

 

Error Handling

Common Errors

ErrorCauseSolution
“error reading file”Missing or unreadable fileVerify the path
“expected an array of objects”JSON not in records orientationProvide a top-level array of objects
“no records found in JSON”Empty JSON arrayProvide at least one record
“error opening Excel file”Invalid or non-xlsx fileVerify the file is a valid .xlsx
“sheet … is empty”Excel sheet has no rowsEnsure the sheet has a header row
“error opening parquet file”Invalid or corrupt .parquet fileVerify the file is a valid Parquet file

 

 

Dependencies

Excel support depends on github.com/xuri/excelize/v2, and Parquet support on github.com/parquet-go/parquet-go; both are pulled in automatically via go get. JSON I/O uses only the Go standard library.

 

 

See Also