Tutorials
Background
How To
Integrations & Extensions
More Help
Configuration
Configuration objects can be used when creating a TileDB context, or when using consolidation and virtual filesystem (VFS) functionality. See Configuration Parameters for a summary of all TileDB configuration options.
Basic Usage
You can create and set configuration objects as follows:
C
C++
Python
R
Java
Go
1
// Create a configuration object
2
tiledb_config_t *config;
3
tiledb_config_alloc(&config, NULL);
4
5
// Set a configuration parameter
6
tiledb_config_set(config, "sm.tile_cache_size", "5000", &error);
7
8
// Get a configuration parameter
9
const char* value;
10
tiledb_config_get(config, "sm.tile_cache_size", &value, &error);
11
12
// Unset a configuration parameter
13
tiledb_config_unset(config, "sm.tile_cache_size", &error);
14
15
// Clean up
16
tiledb_config_free(&config);
Copied!
1
// Create a configuration object
2
Config config;
3
4
// Set a configuration parameter
5
config["sm.tile_cache_size"] = "5000";
6
7
// Get a configuration parameter
8
std::string = config["sm.tile_cache_size"];
9
10
// Unset a configuration parameter
11
config.unset("sm.tile_cache_size");
Copied!
1
# Create a configuration object
2
config = tiledb.Config()
3
4
# Set a configuration parameter
5
config["sm.tile_cache_size"] = 5000
6
7
# Config objects may also be initialized with a dictionary
8
config = tiledb.Config({"sm.tile_cache_size": 5000})
9
10
# Remove a configuration parameter
11
# (resets to the default value)
12
del config["sm.tile_cache_size"]
Copied!
1
# Create a configuration object
2
config <- tiledb_config()
3
4
# Set a configuration parameter
5
config["sm.tile_cache_size"] <- "5000"
6
7
# Get a configuration parameter
8
tile_cache_size <- config["sm.tile_cache_size"]
9
10
# Unset a configuration parameter
11
tiledb_config_unset(config, "sm.tile_cache_size")
Copied!
1
try(Config config = new Config()) {
2
// Set a configuration parameter
3
config.set("sm.tile_cache_size", "5000");
4
5
// Get a configuration parameter
6
String tile_cache_size = config.get("sm.tile_cache_size");
7
8
// Unset a configuration parameter
9
config.unset("sm.tile_cache_size");
10
}
Copied!
1
// Create a configuration object
2
config, _ := tiledb.NewConfig()
3
4
// Set a configuration parameter
5
config.Set("sm.tile_cache_size", "5000");
6
7
// Get a configuration parameter
8
smTileCacheSize, _ := config.Get("sm.tile_cache_size")
9
10
// Unset a configuration parameter
11
config.Unset("sm.tile_cache_size")
12
13
// Clean up
14
config.Free()
Copied!
Saving To / Loading From File
You can save a configuration object into a text file, as well as load a configuration object from a text file, as follows:
C
C++
Python
R
Java
Go
1
// Create a TileDB config
2
tiledb_config_t* config;
3
tiledb_config_alloc(&config, NULL);
4
tiledb_config_set(config, "sm.tile_cache_size", "0", &error);
5
6
// Save to file
7
tiledb_config_save_to_file(config, "tiledb_config.txt", &error);
8
9
// Load from file
10
tiledb_config_t* config_load;
11
tiledb_config_alloc(&config_load, &error);
12
tiledb_config_load_from_file(config_load, "tiledb_config.txt", &error);
13
const char* value;
14
tiledb_config_get(config_load, "sm.tile_cache_size", &value, &error);
15
16
// Clean up
17
tiledb_config_free(&config);
18
tiledb_config_free(&config_load);
Copied!
1
// Save to file
2
Config config;
3
config["sm.tile_cache_size"] = 0;
4
config.save_to_file("tiledb_config.txt");
5
6
// Load from file
7
Config config_load("tiledb_config.txt");
8
std::string tile_cache_size = config_load["sm.tile_cache_size"];
Copied!
1
config = tiledb.Config()
2
config["sm.tile_cache_size"] = 0
3
config.save("tiledb_config.txt")
4
5
config_load = tiledb.Config.load("tiledb_config.txt")
Copied!
1
# Save to file
2
config <- tiledb_config()
3
config["sm.tile_cache_size"] <- 0;
4
tiledb_config_save(config, "tiledb_config.txt")
5
6
# Load from file
7
config_loaded <- tiledb_config_load("tiledb_config.txt")
8
tile_cache_size = config_loaded["sm.tile_cache_size"]
Copied!
1
// Save to file
2
try(Config config = new Config()) {
3
config.set("sm.tile_cache_size", "0");
4
config.saveToFile("tiledb_config.txt");
5
6
// Load from file
7
Config config_load = new Config("tiledb_config.txt");
8
String tile_cache_size = config_load.get("sm.tile_cache_size");
9
}
Copied!
1
// Create a TileDB config
2
config, _ := tiledb.NewConfig()
3
4
// Set a value
5
config.Set("sm.tile_cache_size", "8")
6
7
// Save to file
8
config.SaveToFile(configFileName)
9
10
// Load from file
11
newConfig, _ := tiledb.LoadConfig(configFileName)
12
13
// Retrieve value
14
smTileCacheSize, _ := newConfig.Get("sm.tile_cache_size")
15
16
// Clean up
17
config.Free()
Copied!
Configuration Iterator
You can also use a configuration iterator as follows:
C
C++
Python
R
Java
Go
1
// Create a TileDB config
2
tiledb_config_t* config;
3
tiledb_config_alloc(&config, NULL);
4
5
// Create a TileDB config iterator
6
// You can use any prefix instead of "vfs.s3."
7
tiledb_config_iter_t* config_iter;
8
tiledb_config_iter_alloc(config, "vfs.s3.", &config_iter, &error);
9
10
// Print all configuration parameters that start with "vfs.s3"
11
// Note that the prefix is exluded from the results
12
printf("\nVFS S3 settings:\n");
13
int done = 0;
14
const char *param, *value;
15
tiledb_config_iter_done(config_iter, &done, &error);
16
while (!done) {
17
tiledb_config_iter_here(config_iter, ¶m, &value, &error);
18
printf("\"%s\" : \"%s\"\n", param, value);
19
tiledb_config_iter_next(config_iter, &error);
20
tiledb_config_iter_done(config_iter, &done, &error);
21
}
22
23
// You can reset the iterator as follows
24
tiledb_config_iter_reset(config, config_iter, NULL, NULL);
25
26
// Clean up
27
tiledb_config_free(&config);
28
tiledb_config_iter_free(&config_iter);
Copied!
1
Config config;
2
3
// Print only the S3 settings
4
// You can use any prefix instead of "vfs.s3."
5
// Note that the prefix is exluded from the results
6
std::cout << "\nVFS S3 settings:\n";
7
for (auto i = config.begin("vfs.s3."); i != config.end(); ++i) {
8
auto& p = *i;
9
std::cout << "\"" << p.first << "\" : \"" << p.second << "\"\n";
10
}
Copied!
1
# ... create/open a Config object
2
3
for (key,value) in config.items():
4
print(f"'{key}': '{value}'")
5
6
# keys may optionally be filtered by passing a prefix to `items()`
7
for (key,value) in config.items("vfs.s3."):
8
print(f"'{key}': '{value}'")
Copied!
1
# R has no native iterator but one loop over the config elements
2
# by retrieving the configuration as a vector
3
4
cfg <- as.vector(tiledb_config())
5
6
# print all non-empty config elements
7
for (n in names(cfg))
8
if (cfg[n] != "")
9
cat(n, ":", cfg[n], "\n")
Copied!
1
try(Config config = new Config()) {
2
// Print only the S3 settings
3
// You can use any prefix instead of "vfs.s3."
4
// Note that the prefix is exluded from the results
5
System.out.printf("\nVFS S3 settings:\n");
6
for (Map.Entry me : config.parameters("vfs.s3").entrySet()) {
7
System.out.Printf("\"%s\" : \"%s\"\n", p.getKey(), p.getValue());
8
}
9
}
Copied!
1
fmt.Println("VFS S3 settings:\n")
2
3
config, _ := NewConfig()
4
5
// Iterate the configuration
6
iter, _ := config.Iterate("vfs.s3.")
7
8
for ; !iter.IsDone(); _ = iter.Next() {
9
// Get current param, value from iterator
10
param, value, _ := iter.Here()
11
fmt.Printf("%s: %s\n", *param, *value)
12
}
Copied!
Configuration Parameters
Below we provide a table with all the TileDB configuration parameters, along with their description and default values. See Configuration for information on how to set them.
Parameter
Default Value
Description
"sm.check_coord_dups""true"This is applicable only if
sm.dedup_coords is false. If true, an error will be thrown if there are cells with duplicate coordinates during sparse fragment writes. If false and there are duplicates, the duplicates will be written without errors."sm.check_coord_oob""true"If
true, an error will be thrown if there are cells with coordinates lying outside the array domain during sparse fragment writes."sm.check_global_order""true"If
true, an error will be thrown if the coordinates are not in the global order. Applicable only to sparse writes in the global order."sm.consolidation.amplification""1.0"The factor by which the size of the dense fragment resulting from consolidating a set of fragments (containing at least one dense fragment) can be amplified. This is important when the union of the non-empty domains of the fragments to be consolidated have a lot of empty cells, which the consolidated fragment will have to fill with the special fill value (since the resulting fragment is dense).
"sm.consolidation.buffer_size""50000000"The size (in bytes) of the attribute buffers used during consolidation.
"sm.consolidation.step_max_frags""4294967295"The maximum number of fragments to consolidate in a single step.
"sm.consolidation.step_min_frags""4294967295"The minimum number of fragments to consolidate in a single step.
"sm.consolidation.step_size_ratio""0"The size ratio of two (“adjacent”) fragments must be larger than this value to be considered for consolidation in a single step.
"sm.consolidation.steps""4294967295"The number of consolidation steps to be performed when executing the consolidation algorithm.
"sm.consolidation.mode""fragments"The consolidation mode, one of
fragments (consolidate all fragments), fragment_meta (consolidate only fragment metadata footers to a single file), or array_meta (consolidate array metadata only)."sm.vacuum.mode""fragments"The vacuuming mode, one of
fragments (remove consolidated fragments), fragment_meta (remove only consolidated fragment metadata), or array_meta (remove consolidated array metadata files)."sm.dedup_coords""false"If
true, cells with duplicate coordinates will be removed during sparse fragment writes. Note that ties during deduplication are broken arbitrarily."sm.enable_signal_handlers""true"Determines whether or not TileDB will install signal handlers.
"sm.memory_budget""5GB"The memory budget for tiles of fixed-sized attributes (or offsets for var-sized attributes) to be fetched during reads. This is applicable to dense reads, sparse ordered reads and "legacy" reader modes.
"sm.memory_budget_var""10GB"The memory budget for tiles of var-sized attributes to be fetched during reads. This is applicable to dense reads and sparse ordered reads and "legacy" reader modes.
"sm.mem.malloc_trim""true"Should malloc_trim be called on context and query destruction? This might reduce residual memory usage.
"sm.mem.total_budget""10GB"Memory budget for refactored readers and writers. This includes sparse unordered reads, and dense reads with refactored reader.
"sm.mem.reader.sparse_global_order.ratio_coords"0.5Ratio of the budget allocated for coordinates in the sparse global order reader.
"sm.mem.reader.sparse_global_order.ratio_query_condition"0.25Ratio of the budget allocated for the query condition in the sparse global order reader.
Last modified 4mo ago