TileDB Go Bindings

This package provides TileDB golang bindings via cgo. The bindings have been designed to be idomatic Go. runtime.SetFinalizer is used to ensure proper free'ing of C heap allocated structures.

Quick Links

• GoDoc API documentation: https://pkg.go.dev/github.com/TileDB-Inc/TileDB-Go
• Full developer documentation for all APIs and integrations: https://cloud.tiledb.com/academy

Installation

Supported Platforms

Currently the following platforms are supported:

• Linux
• macOS (OSX)

Prerequisites

This package requires the TileDB shared library be installed and on the system path. Visit the TileDB GitHub repository.

Environment setup

Make sure you have Go installed on your system. This guide assumes you are using Go 1.17 or later, which fully supports modules. You can check your Go version by running go version.

Initialization steps

go mod init github.com/<github_username>/repository_name

Go Installation

To install these bindings you can use go get:

 go get -v github.com/TileDB-Inc/TileDB-Go

To install package with test dependencies:

go get -v -t github.com/TileDB-Inc/TileDB-Go

Go Testing

Package tests can be run with:

go test github.com/TileDB-Inc/TileDB-Go

Compatibility

TileDB-Go follows semantic versioning. Currently TileDB core library does not, as such the below table reference which versions are compatible.

TileDB-Go Version	TileDB Version
0.7.X	1.6.X
0.8.0	1.7.0
0.8.1	1.7.0
0.8.2	1.7.2
0.8.3	>=1.7.3
0.8.4	>=1.7.3
0.8.5	>=1.7.3
0.9.0	2.0.X
0.10.0	2.1.X
0.11.0	2.2.X
0.12.0	2.3.X
0.13.0	>=2.4.X
0.14.0	>=2.5.X
0.15.0	>=2.8.X
0.16.0	2.10.X
0.17.0	2.11.X
0.18.0	2.12.X
0.19.0	2.13.X
0.20.0	2.14.X
0.21.0	2.15.X
0.22.0	2.16.X
0.23.0	2.17.X
0.24.0	2.18.X
0.25.0	2.19.X
0.26.0	2.20.X
0.27.0	2.21.X
0.28.0	2.22.X
0.29.0	2.23.X
0.30.0	2.24.X
0.31.0	2.25.X
0.32.0	2.26.X
0.33.0	2.26.X
0.34.0	2.27.X
0.35.0	2.27.X
0.36.0	2.28.X
0.37.0	2.28.X
0.38.0	2.29.X

Deprecated Functionality

0.21.0

The query methods (Set)?Buffer(Var|Nullable|Var|Unsafe)* are deprecated because the corresponding TileDB core methods are removed. The methods will be supported for 2 releases and are expected to be removed in release 0.23. It is recommended to use the proper combination of (Set|Get)DataBuffer, (Set|Get)ValidityBuffer and (Set|Get)OffsetBuffer.

0.23.1

The query methods (Add|Get)?Range are deprecated because they are deprecated in TileDB core. It is recommend to use the Subarray type for building queries. The methods will be removed in the release following their removal from TileDB core.

0.24.0

Array.DeleteFragments is deprecated in favor of tiledb.DeleteFragments which binds to C.tiledb_array_delete_fragments_v2 the preferred method to delete fragments in TileDB 2.18.0.

0.30.3

All deprecated APIs in TileDB-Go are removed as the corresponding C-APIs will be removed in the following TileDB release.

0.33.0

SerializeArrayMaxBufferSizes is removed as the underlying core method tiledb_serialize_array_max_buffer_sizes is deprecated in TileDB 2.27.0.

0.36.0

Array.Create is deprecated in favor of CreateArray. Array.Consolidate is deprecated in favor of ConsolidateArray. Array.Vacuum is deprecated in favor of VacuumArray.

0.38.0

VFS.VisitRecursive is deprecated in favor of VFS.VisitRecursiveV2. VFS.VisitRecursiveCallback is deprecated in favor of VFS.VisitRecursiveCallbackV2.

Breaking Changes

0.36.0

Free will no longer call Close for Group and Array objects. The caller is responsible for closing the Array or Group after operations such as writing metadata or modifying group members.