Skip to content

Commit 68a1472

Browse files
teo-tsirpanisteo-tsirpanis
authored
Add current domain API examples. (#5134)
[SC-49732](https://app.shortcut.com/tiledb-inc/story/49732/current-domain-examples) This PR adds examples in the C and C++ APIs, that create an array, print its current domain, expand it through array schema evolution, and print it again. --- TYPE: NO_HISTORY
1 parent 9fed575 commit 68a1472

File tree

2 files changed

+391
-0
lines changed

2 files changed

+391
-0
lines changed

‎examples/c_api/current_domain.c‎

Lines changed: 228 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,228 @@
1+
/**
2+
* @file current_domain.c
3+
*
4+
* @section LICENSE
5+
*
6+
* The MIT License
7+
*
8+
* @copyright Copyright (c) 2024 TileDB, Inc.
9+
*
10+
* Permission is hereby granted, free of charge, to any person obtaining a copy
11+
* of this software and associated documentation files (the "Software"), to deal
12+
* in the Software without restriction, including without limitation the rights
13+
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
14+
* copies of the Software, and to permit persons to whom the Software is
15+
* furnished to do so, subject to the following conditions:
16+
*
17+
* The above copyright notice and this permission notice shall be included in
18+
* all copies or substantial portions of the Software.
19+
*
20+
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
21+
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
22+
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
23+
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
24+
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
25+
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
26+
* THE SOFTWARE.
27+
*
28+
* @section DESCRIPTION
29+
*
30+
* When run, this program will create a simple 1D sparse array with a current
31+
* domain, print it, expand it with array schema evolution, and print it again.
32+
*/
33+
34+
#include <stdio.h>
35+
#include <stdlib.h>
36+
#include <tiledb/tiledb.h>
37+
#include <tiledb/tiledb_experimental.h>
38+
39+
// Name of array.
40+
const char* array_name = "current_domain_array";
41+
42+
void create_array() {
43+
// Create TileDB context
44+
tiledb_ctx_t* ctx;
45+
tiledb_ctx_alloc(NULL, &ctx);
46+
47+
// The array will be 1000x1 with dimension "d1", with domain [1,1000].
48+
int dim_domain[] = {1, 1000};
49+
int tile_extent = 50;
50+
tiledb_dimension_t* d1;
51+
tiledb_dimension_alloc(
52+
ctx, "d1", TILEDB_INT32, &dim_domain[0], &tile_extent, &d1);
53+
54+
// Create domain
55+
tiledb_domain_t* domain;
56+
tiledb_domain_alloc(ctx, &domain);
57+
tiledb_domain_add_dimension(ctx, domain, d1);
58+
59+
// Create current domain
60+
tiledb_current_domain_t* current_domain;
61+
tiledb_current_domain_create(ctx, &current_domain);
62+
63+
// Create an n-dimensional rectangle
64+
tiledb_ndrectangle_t* ndrect;
65+
tiledb_ndrectangle_alloc(ctx, domain, &ndrect);
66+
67+
// Assign the range [1, 100] to the rectangle's first dimension
68+
int32_t expanded_current_domain[] = {1, 100};
69+
tiledb_range_t range = {
70+
&expanded_current_domain[0],
71+
sizeof(expanded_current_domain[0]),
72+
&expanded_current_domain[1],
73+
sizeof(expanded_current_domain[1])};
74+
tiledb_ndrectangle_set_range_for_name(ctx, ndrect, "d1", &range);
75+
76+
// Assign the rectangle to the current domain
77+
tiledb_current_domain_set_ndrectangle(current_domain, ndrect);
78+
79+
// Create a single attribute "a" so each cell can store an integer
80+
tiledb_attribute_t* a;
81+
tiledb_attribute_alloc(ctx, "a", TILEDB_INT32, &a);
82+
83+
// Create array schema
84+
tiledb_array_schema_t* array_schema;
85+
tiledb_array_schema_alloc(ctx, TILEDB_SPARSE, &array_schema);
86+
tiledb_array_schema_set_cell_order(ctx, array_schema, TILEDB_ROW_MAJOR);
87+
tiledb_array_schema_set_tile_order(ctx, array_schema, TILEDB_ROW_MAJOR);
88+
tiledb_array_schema_set_domain(ctx, array_schema, domain);
89+
tiledb_array_schema_add_attribute(ctx, array_schema, a);
90+
91+
// Assign the current domain to the array schema
92+
tiledb_array_schema_set_current_domain(ctx, array_schema, current_domain);
93+
94+
// Create array
95+
tiledb_array_create(ctx, array_name, array_schema);
96+
97+
// Clean up
98+
tiledb_array_schema_free(&array_schema);
99+
tiledb_attribute_free(&a);
100+
tiledb_ndrectangle_free(&ndrect);
101+
tiledb_current_domain_free(&current_domain);
102+
tiledb_domain_free(&domain);
103+
tiledb_dimension_free(&d1);
104+
tiledb_ctx_free(&ctx);
105+
}
106+
107+
void print_current_domain() {
108+
// Create TileDB context
109+
tiledb_ctx_t* ctx;
110+
tiledb_ctx_alloc(NULL, &ctx);
111+
112+
// Load array schema
113+
tiledb_array_schema_t* array_schema;
114+
tiledb_array_schema_load(ctx, array_name, &array_schema);
115+
116+
// Get current domain
117+
tiledb_current_domain_t* current_domain;
118+
tiledb_array_schema_get_current_domain(ctx, array_schema, &current_domain);
119+
120+
// Check if current domain is empty
121+
uint32_t is_empty;
122+
tiledb_current_domain_get_is_empty(current_domain, &is_empty);
123+
124+
if (is_empty) {
125+
printf("Current domain: empty\n");
126+
} else {
127+
// Get current domain type
128+
tiledb_current_domain_type_t current_domain_type;
129+
tiledb_current_domain_get_type(current_domain, &current_domain_type);
130+
131+
if (current_domain_type == TILEDB_NDRECTANGLE) {
132+
printf("Current domain type: NDRECTANGLE\n");
133+
134+
// Get the ND rectangle
135+
tiledb_ndrectangle_t* ndrect;
136+
tiledb_current_domain_get_ndrectangle(current_domain, &ndrect);
137+
138+
tiledb_range_t range;
139+
tiledb_ndrectangle_get_range_from_name(ctx, ndrect, "d1", &range);
140+
141+
printf(
142+
"Current domain range: [%d, %d]\n",
143+
*(int*)range.min,
144+
*(int*)range.max);
145+
146+
// Clean up
147+
tiledb_ndrectangle_free(&ndrect);
148+
} else {
149+
printf("Current domain type: unknown\n");
150+
}
151+
}
152+
153+
// Clean up
154+
tiledb_current_domain_free(&current_domain);
155+
tiledb_array_schema_free(&array_schema);
156+
tiledb_ctx_free(&ctx);
157+
}
158+
159+
void expand_current_domain() {
160+
// Create TileDB context
161+
tiledb_ctx_t* ctx;
162+
tiledb_ctx_alloc(NULL, &ctx);
163+
164+
// Load array schema
165+
tiledb_array_schema_t* array_schema;
166+
tiledb_array_schema_load(ctx, array_name, &array_schema);
167+
168+
// Get domain
169+
tiledb_domain_t* domain;
170+
tiledb_array_schema_get_domain(ctx, array_schema, &domain);
171+
172+
// Create schema evolution
173+
tiledb_array_schema_evolution_t* schema_evolution;
174+
tiledb_array_schema_evolution_alloc(ctx, &schema_evolution);
175+
176+
// Create the new current domain
177+
tiledb_current_domain_t* new_current_domain;
178+
tiledb_current_domain_create(ctx, &new_current_domain);
179+
180+
// Create an n-dimensional rectangle
181+
tiledb_ndrectangle_t* ndrect;
182+
tiledb_ndrectangle_alloc(ctx, domain, &ndrect);
183+
184+
// Assign the range [1, 200] to the rectangle's first dimension
185+
int32_t expanded_current_domain[] = {1, 200};
186+
tiledb_range_t range = {
187+
&expanded_current_domain[0],
188+
sizeof(expanded_current_domain[0]),
189+
&expanded_current_domain[1],
190+
sizeof(expanded_current_domain[1])};
191+
tiledb_ndrectangle_set_range_for_name(ctx, ndrect, "d1", &range);
192+
193+
// Set the rectangle to the current domain
194+
tiledb_current_domain_set_ndrectangle(new_current_domain, ndrect);
195+
196+
// Expand the current domain
197+
tiledb_array_schema_evolution_expand_current_domain(
198+
ctx, schema_evolution, new_current_domain);
199+
200+
// Evolve the array
201+
tiledb_array_evolve(ctx, array_name, schema_evolution);
202+
203+
// Clean up
204+
tiledb_ndrectangle_free(&ndrect);
205+
tiledb_current_domain_free(&new_current_domain);
206+
tiledb_array_schema_evolution_free(&schema_evolution);
207+
tiledb_domain_free(&domain);
208+
tiledb_array_schema_free(&array_schema);
209+
tiledb_ctx_free(&ctx);
210+
}
211+
212+
int main() {
213+
// Get object type
214+
tiledb_ctx_t* ctx;
215+
tiledb_ctx_alloc(NULL, &ctx);
216+
tiledb_object_t type;
217+
tiledb_object_type(ctx, array_name, &type);
218+
tiledb_ctx_free(&ctx);
219+
220+
if (type != TILEDB_ARRAY) {
221+
create_array();
222+
print_current_domain();
223+
expand_current_domain();
224+
}
225+
226+
print_current_domain();
227+
return 0;
228+
}

‎examples/cpp_api/current_domain.cc‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
/**
2+
* @file current_domain.cc
3+
*
4+
* @section LICENSE
5+
*
6+
* The MIT License
7+
*
8+
* @copyright Copyright (c) 2024 TileDB, Inc.
9+
*
10+
* Permission is hereby granted, free of charge, to any person obtaining a copy
11+
* of this software and associated documentation files (the "Software"), to deal
12+
* in the Software without restriction, including without limitation the rights
13+
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
14+
* copies of the Software, and to permit persons to whom the Software is
15+
* furnished to do so, subject to the following conditions:
16+
*
17+
* The above copyright notice and this permission notice shall be included in
18+
* all copies or substantial portions of the Software.
19+
*
20+
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
21+
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
22+
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
23+
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
24+
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
25+
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
26+
* THE SOFTWARE.
27+
*
28+
* @section DESCRIPTION
29+
*
30+
* When run, this program will create a simple 1D sparse array with a current
31+
* domain, print it, expand it with array schema evolution, and print it again.
32+
*/
33+
34+
#include <iostream>
35+
#include <numeric>
36+
#include <tiledb/tiledb>
37+
#include <tiledb/tiledb_experimental>
38+
39+
using namespace tiledb;
40+
41+
// Name of array.
42+
std::string array_name("current_domain_example_array");
43+
44+
void create_array(Context& ctx, const std::string& array_uri) {
45+
// Create a TileDB domain
46+
Domain domain(ctx);
47+
48+
// Add a dimension to the domain
49+
auto d1 = Dimension::create<int>(ctx, "d1", {{1, 1000}}, 50);
50+
domain.add_dimension(d1);
51+
52+
// Create a CurrentDomain object
53+
CurrentDomain current_domain(ctx);
54+
55+
// Create an NDRectangle object
56+
NDRectangle ndrect(ctx, domain);
57+
58+
// Assign the range [1, 100] to the rectangle's first dimension
59+
ndrect.set_range<int32_t>("d1", 1, 100);
60+
61+
// Assign the NDRectangle to the CurrentDomain
62+
current_domain.set_ndrectangle(ndrect);
63+
64+
// Create a TileDB sparse array schema
65+
ArraySchema schema(ctx, TILEDB_SPARSE);
66+
schema.set_domain(domain)
67+
.set_order({{TILEDB_ROW_MAJOR, TILEDB_ROW_MAJOR}})
68+
.set_capacity(100)
69+
.set_cell_order(TILEDB_ROW_MAJOR)
70+
.set_tile_order(TILEDB_ROW_MAJOR);
71+
72+
// Create a single attribute
73+
schema.add_attribute(Attribute::create<int>(ctx, "a"));
74+
75+
// Assign the current domain to the array schema
76+
ArraySchemaExperimental::set_current_domain(ctx, schema, current_domain);
77+
78+
// Create the (empty) array on disk
79+
Array::create(array_uri, schema);
80+
}
81+
82+
void print_current_domain(Context& ctx) {
83+
// Get array schema
84+
ArraySchema schema(ctx, array_name);
85+
86+
// Get current domain
87+
CurrentDomain current_domain =
88+
ArraySchemaExperimental::current_domain(ctx, schema);
89+
90+
// Check if the current domain is empty
91+
if (current_domain.is_empty()) {
92+
std::cout << "Current domain: empty" << std::endl;
93+
return;
94+
}
95+
96+
// Get the current domain type
97+
tiledb_current_domain_type_t current_domain_type = current_domain.type();
98+
99+
// Check the current domain type
100+
if (current_domain_type != TILEDB_NDRECTANGLE) {
101+
std::cout << "Current domain type: unknown" << std::endl;
102+
return;
103+
}
104+
105+
std::cout << "Current domain type: NDRECTANGLE" << std::endl;
106+
107+
// Get the current domain's NDRectangle
108+
NDRectangle ndrect = current_domain.ndrectangle();
109+
110+
// Get the range of the rectangle's first dimension
111+
std::array<int32_t, 2> range = ndrect.range<int32_t>("d1");
112+
113+
// Print the range
114+
std::cout << "Current domain range: [" << range[0] << ", " << range[1] << "]"
115+
<< std::endl;
116+
}
117+
118+
void expand_current_domain(Context& ctx) {
119+
// Get the array schema
120+
ArraySchema schema(ctx, array_name);
121+
122+
// Get the domain
123+
Domain domain = schema.domain();
124+
125+
// Create an ArraySchemaEvolution object
126+
ArraySchemaEvolution schema_evolution(ctx);
127+
128+
// Create the new CurrentDomain object
129+
CurrentDomain new_current_domain(ctx);
130+
131+
// Create an NDRectangle object
132+
NDRectangle ndrect(ctx, domain);
133+
134+
// Assign the range [1, 200] to the rectangle's first dimension
135+
ndrect.set_range<int32_t>("d1", 1, 200);
136+
137+
// Set the NDRectangle to the CurrentDomain
138+
new_current_domain.set_ndrectangle(ndrect);
139+
140+
// Set the current domain to the array schema evolution
141+
schema_evolution.expand_current_domain(new_current_domain);
142+
143+
// Evolve the array
144+
schema_evolution.array_evolve(array_name);
145+
}
146+
147+
int main() {
148+
Context ctx;
149+
150+
// Create a new simple array
151+
create_array(ctx, array_name);
152+
153+
// Print the current domain
154+
print_current_domain(ctx);
155+
156+
// Expand the current domain
157+
expand_current_domain(ctx);
158+
159+
// Print the current domain again
160+
print_current_domain(ctx);
161+
162+
return 0;
163+
}

0 commit comments

Comments
 (0)