node-s3tables 0.0.1 → 0.0.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +190 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1 +1,191 @@
|
|
|
1
1
|
# node-s3tables
|
|
2
|
+
|
|
3
|
+
A Node.js library for interacting with AWS S3 Tables using the Iceberg REST API.
|
|
4
|
+
|
|
5
|
+
## Installation
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install node-s3tables
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## Quick Start
|
|
12
|
+
|
|
13
|
+
```javascript
|
|
14
|
+
import { getMetadata, addSchema, addPartitionSpec } from 'node-s3tables';
|
|
15
|
+
|
|
16
|
+
// Get table metadata
|
|
17
|
+
const metadata = await getMetadata({
|
|
18
|
+
tableArn:
|
|
19
|
+
'arn:aws:s3tables:us-west-2:123456789012:bucket/my-bucket/table/my-table-id',
|
|
20
|
+
});
|
|
21
|
+
|
|
22
|
+
// Add a new schema
|
|
23
|
+
await addSchema({
|
|
24
|
+
tableBucketARN: 'arn:aws:s3tables:us-west-2:123456789012:bucket/my-bucket',
|
|
25
|
+
namespace: 'my_namespace',
|
|
26
|
+
name: 'my_table',
|
|
27
|
+
schemaId: 2,
|
|
28
|
+
fields: [
|
|
29
|
+
{ id: 1, name: 'id', required: true, type: 'long' },
|
|
30
|
+
{ id: 2, name: 'name', required: false, type: 'string' },
|
|
31
|
+
],
|
|
32
|
+
});
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
## API Reference
|
|
36
|
+
|
|
37
|
+
### getMetadata(params)
|
|
38
|
+
|
|
39
|
+
Retrieves Iceberg metadata for an S3 table.
|
|
40
|
+
|
|
41
|
+
**Parameters:**
|
|
42
|
+
|
|
43
|
+
- `params.tableArn` (string) - The ARN of the table
|
|
44
|
+
- OR `params.tableBucketARN` (string) + `params.namespace` (string) + `params.name` (string)
|
|
45
|
+
- `params.config` (S3TablesClientConfig, optional) - AWS SDK configuration
|
|
46
|
+
|
|
47
|
+
**Returns:** Promise<IcebergMetadata>
|
|
48
|
+
|
|
49
|
+
```javascript
|
|
50
|
+
// Using table ARN
|
|
51
|
+
const metadata = await getMetadata({
|
|
52
|
+
tableArn:
|
|
53
|
+
'arn:aws:s3tables:us-west-2:123456789012:bucket/my-bucket/table/my-table-id',
|
|
54
|
+
});
|
|
55
|
+
|
|
56
|
+
// Using bucket ARN + namespace + name
|
|
57
|
+
const metadata = await getMetadata({
|
|
58
|
+
tableBucketARN: 'arn:aws:s3tables:us-west-2:123456789012:bucket/my-bucket',
|
|
59
|
+
namespace: 'my_namespace',
|
|
60
|
+
name: 'my_table',
|
|
61
|
+
});
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
### addSchema(params)
|
|
65
|
+
|
|
66
|
+
Adds a new schema to an S3 table and sets it as current.
|
|
67
|
+
|
|
68
|
+
**Parameters:**
|
|
69
|
+
|
|
70
|
+
- `params.tableBucketARN` (string) - The ARN of the table bucket
|
|
71
|
+
- `params.namespace` (string) - The namespace name
|
|
72
|
+
- `params.name` (string) - The table name
|
|
73
|
+
- `params.schemaId` (number) - The new schema ID
|
|
74
|
+
- `params.fields` (IcebergSchemaField[]) - Array of schema fields
|
|
75
|
+
- `params.credentials` (AwsCredentialIdentity, optional) - AWS credentials
|
|
76
|
+
|
|
77
|
+
**Returns:** Promise<string>
|
|
78
|
+
|
|
79
|
+
```javascript
|
|
80
|
+
await addSchema({
|
|
81
|
+
tableBucketARN: 'arn:aws:s3tables:us-west-2:123456789012:bucket/my-bucket',
|
|
82
|
+
namespace: 'sales',
|
|
83
|
+
name: 'daily_sales',
|
|
84
|
+
schemaId: 2,
|
|
85
|
+
fields: [
|
|
86
|
+
{ id: 1, name: 'sale_date', required: false, type: 'date' },
|
|
87
|
+
{ id: 2, name: 'product_category', required: false, type: 'string' },
|
|
88
|
+
{ id: 3, name: 'sales_amount', required: false, type: 'double' },
|
|
89
|
+
],
|
|
90
|
+
});
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
### addPartitionSpec(params)
|
|
94
|
+
|
|
95
|
+
Adds a new partition specification to an S3 table and sets it as default.
|
|
96
|
+
|
|
97
|
+
**Parameters:**
|
|
98
|
+
|
|
99
|
+
- `params.tableBucketARN` (string) - The ARN of the table bucket
|
|
100
|
+
- `params.namespace` (string) - The namespace name
|
|
101
|
+
- `params.name` (string) - The table name
|
|
102
|
+
- `params.specId` (number) - The new partition spec ID
|
|
103
|
+
- `params.fields` (IcebergPartitionField[]) - Array of partition fields
|
|
104
|
+
- `params.credentials` (AwsCredentialIdentity, optional) - AWS credentials
|
|
105
|
+
|
|
106
|
+
**Returns:** Promise<string>
|
|
107
|
+
|
|
108
|
+
```javascript
|
|
109
|
+
await addPartitionSpec({
|
|
110
|
+
tableBucketARN: 'arn:aws:s3tables:us-west-2:123456789012:bucket/my-bucket',
|
|
111
|
+
namespace: 'sales',
|
|
112
|
+
name: 'daily_sales',
|
|
113
|
+
specId: 1,
|
|
114
|
+
fields: [
|
|
115
|
+
{
|
|
116
|
+
'field-id': 1000,
|
|
117
|
+
name: 'sale_date_day',
|
|
118
|
+
'source-id': 1,
|
|
119
|
+
transform: 'day',
|
|
120
|
+
},
|
|
121
|
+
{
|
|
122
|
+
'field-id': 1001,
|
|
123
|
+
name: 'product_category',
|
|
124
|
+
'source-id': 2,
|
|
125
|
+
transform: 'identity',
|
|
126
|
+
},
|
|
127
|
+
],
|
|
128
|
+
});
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
## Type Definitions
|
|
132
|
+
|
|
133
|
+
### IcebergSchemaField
|
|
134
|
+
|
|
135
|
+
```typescript
|
|
136
|
+
interface IcebergSchemaField {
|
|
137
|
+
id: number;
|
|
138
|
+
name: string;
|
|
139
|
+
type: IcebergType;
|
|
140
|
+
required: boolean;
|
|
141
|
+
doc?: string;
|
|
142
|
+
}
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
### IcebergPartitionField
|
|
146
|
+
|
|
147
|
+
```typescript
|
|
148
|
+
interface IcebergPartitionField {
|
|
149
|
+
'field-id': number;
|
|
150
|
+
name: string;
|
|
151
|
+
'source-id': number;
|
|
152
|
+
transform: IcebergTransform;
|
|
153
|
+
}
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
### IcebergType
|
|
157
|
+
|
|
158
|
+
Supported primitive types:
|
|
159
|
+
|
|
160
|
+
- `'boolean'`, `'int'`, `'long'`, `'float'`, `'double'`
|
|
161
|
+
- `'date'`, `'time'`, `'timestamp'`, `'timestamptz'`
|
|
162
|
+
- `'string'`, `'uuid'`, `'binary'`
|
|
163
|
+
- `'decimal(precision,scale)'`, `'fixed[length]'`
|
|
164
|
+
|
|
165
|
+
Complex types:
|
|
166
|
+
|
|
167
|
+
- List: `{ type: 'list', element: IcebergType, 'element-required': boolean }`
|
|
168
|
+
- Map: `{ type: 'map', key: IcebergType, value: IcebergType, 'value-required': boolean }`
|
|
169
|
+
- Struct: `{ type: 'struct', fields: IcebergSchemaField[] }`
|
|
170
|
+
|
|
171
|
+
### IcebergTransform
|
|
172
|
+
|
|
173
|
+
Supported partition transforms:
|
|
174
|
+
|
|
175
|
+
- `'identity'` - Use the field value as-is
|
|
176
|
+
- `'year'`, `'month'`, `'day'`, `'hour'` - Date/time transforms
|
|
177
|
+
- `'bucket[N]'` - Hash bucket with N buckets
|
|
178
|
+
- `'truncate[N]'` - Truncate strings to N characters
|
|
179
|
+
|
|
180
|
+
## Configuration
|
|
181
|
+
|
|
182
|
+
The library uses the AWS SDK for authentication. Configure credentials using:
|
|
183
|
+
|
|
184
|
+
- Environment variables (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`)
|
|
185
|
+
- AWS credentials file (`~/.aws/credentials`)
|
|
186
|
+
- IAM roles (when running on EC2/Lambda)
|
|
187
|
+
- Or pass credentials directly to functions
|
|
188
|
+
|
|
189
|
+
## License
|
|
190
|
+
|
|
191
|
+
MIT
|