0
# Constraint System
1

2
The constraint system provides a three-dimensional constraint framework supporting ENABLE/DISABLE, VALIDATE/NOVALIDATE, and RELY/NORELY traits for Hive table constraints.
3

4
## Capabilities
5

6
### Constraint Traits
7

8
Complete constraint trait specification with three dimensions of constraint behavior.
9

10
```java { .api }
11
/**
12
 * Complete constraint trait specification
13
 * Represents three-dimensional constraint behavior: enable/disable, validate/no-validate, rely/no-rely
14
 */
15
public class SqlHiveConstraintTrait {
16
    /**
17
     * Creates a constraint trait with all three dimensions
18
     * @param enable Enable or disable literal (ENABLE/DISABLE)
19
     * @param validate Validate or no-validate literal (VALIDATE/NOVALIDATE)  
20
     * @param rely Rely or no-rely literal (RELY/NORELY)
21
     */
22
    public SqlHiveConstraintTrait(SqlLiteral enable, SqlLiteral validate, SqlLiteral rely);
23

24
    /**
25
     * Converts constraint trait to SQL representation
26
     * @param writer SQL writer for output
27
     * @param leftPrec Left precedence
28
     * @param rightPrec Right precedence
29
     */
30
    public void unparse(SqlWriter writer, int leftPrec, int rightPrec);
31

32
    /**
33
     * Checks if constraint is enabled
34
     * @return true if constraint is enabled, false otherwise
35
     */
36
    public boolean isEnable();
37

38
    /**
39
     * Checks if constraint validation is enabled
40
     * @return true if constraint validation is enabled, false otherwise
41
     */
42
    public boolean isValidate();
43

44
    /**
45
     * Checks if constraint rely is enabled
46
     * @return true if constraint rely is enabled, false otherwise
47
     */
48
    public boolean isRely();
49
}
50
```
51

52
### Constraint Enable/Disable
53

54
Control whether constraints are enabled or disabled.
55

56
```java { .api }
57
/**
58
 * Constraint enable/disable options
59
 * Controls whether the constraint is active
60
 */
61
public enum SqlHiveConstraintEnable {
62
    /** Enable the constraint */
63
    ENABLE,
64
    
65
    /** Disable the constraint */
66
    DISABLE;
67

68
    /**
69
     * Creates SQL literal symbol for the enable state
70
     * @param pos Parser position information
71
     * @return SqlLiteral representing the enable state
72
     */
73
    public SqlLiteral symbol(SqlParserPos pos);
74
}
75
```
76

77
### Constraint Validation
78

79
Control whether constraints are validated during data operations.
80

81
```java { .api }
82
/**
83
 * Constraint validate/no-validate options
84
 * Controls whether constraint validation occurs during data operations
85
 */
86
public enum SqlHiveConstraintValidate {
87
    /** Validate constraint during data operations */
88
    VALIDATE,
89
    
90
    /** Do not validate constraint during data operations */
91
    NOVALIDATE;
92

93
    /**
94
     * Creates SQL literal symbol for the validation state
95
     * @param pos Parser position information
96
     * @return SqlLiteral representing the validation state
97
     */
98
    public SqlLiteral symbol(SqlParserPos pos);
99
}
100
```
101

102
### Constraint Reliability
103

104
Control whether the query optimizer can rely on constraints for optimization.
105

106
```java { .api }
107
/**
108
 * Constraint rely/no-rely options
109
 * Controls whether the optimizer can rely on the constraint for query optimization
110
 */
111
public enum SqlHiveConstraintRely {
112
    /** Optimizer can rely on the constraint */
113
    RELY,
114
    
115
    /** Optimizer cannot rely on the constraint */
116
    NORELY;
117

118
    /**
119
     * Creates SQL literal symbol for the rely state
120
     * @param pos Parser position information
121
     * @return SqlLiteral representing the rely state
122
     */
123
    public SqlLiteral symbol(SqlParserPos pos);
124
}
125
```
126

127
## Usage Examples
128

129
### Basic Constraint Trait Creation
130

131
```java
132
// Create constraint traits programmatically
133
SqlParserPos pos = SqlParserPos.ZERO;
134

135
// Create ENABLE VALIDATE RELY trait (default/recommended)
136
SqlLiteral enable = SqlHiveConstraintEnable.ENABLE.symbol(pos);
137
SqlLiteral validate = SqlHiveConstraintValidate.VALIDATE.symbol(pos);
138
SqlLiteral rely = SqlHiveConstraintRely.RELY.symbol(pos);
139

140
SqlHiveConstraintTrait defaultTrait = new SqlHiveConstraintTrait(enable, validate, rely);
141

142
// Create DISABLE NOVALIDATE NORELY trait (minimal constraint)
143
SqlLiteral disable = SqlHiveConstraintEnable.DISABLE.symbol(pos);
144
SqlLiteral novalidate = SqlHiveConstraintValidate.NOVALIDATE.symbol(pos);
145
SqlLiteral norely = SqlHiveConstraintRely.NORELY.symbol(pos);
146

147
SqlHiveConstraintTrait minimalTrait = new SqlHiveConstraintTrait(disable, novalidate, norely);
148

149
// Check trait properties
150
boolean isEnabled = defaultTrait.isEnable();        // true
151
boolean isValidated = defaultTrait.isValidate();    // true
152
boolean isReliable = defaultTrait.isRely();         // true
153

154
boolean isDisabled = minimalTrait.isEnable();       // false
155
boolean isNotValidated = minimalTrait.isValidate(); // false
156
boolean isNotReliable = minimalTrait.isRely();      // false
157
```
158

159
### SQL Constraint Syntax
160

161
```sql
162
-- Table creation with constraints and traits
163
CREATE TABLE customer_data (
164
    customer_id BIGINT,
165
    email STRING,
166
    phone STRING,
167
    registration_date DATE,
168
    
169
    -- Primary key with default trait (ENABLE VALIDATE RELY)
170
    PRIMARY KEY (customer_id) ENABLE VALIDATE RELY,
171
    
172
    -- NOT NULL constraint with custom trait
173
    CONSTRAINT nn_email NOT NULL (email) ENABLE NOVALIDATE RELY,
174
    
175
    -- Unique constraint with minimal enforcement
176
    CONSTRAINT uk_email UNIQUE (email) DISABLE NOVALIDATE NORELY
177
);
178

179
-- Alter table to modify constraint traits
180
ALTER TABLE customer_data 
181
CHANGE CONSTRAINT nn_email 
182
NOT NULL (email) ENABLE VALIDATE RELY;
183
```
184

185
### Constraint Trait Utility Methods
186

187
The `HiveDDLUtils` class provides utility methods for working with constraint traits:
188

189
```java
190
// Default constraint trait (ENABLE NOVALIDATE RELY)
191
byte defaultTrait = HiveDDLUtils.defaultTrait();
192

193
// Modify traits
194
byte enabledTrait = HiveDDLUtils.enableConstraint(defaultTrait);
195
byte disabledTrait = HiveDDLUtils.disableConstraint(defaultTrait);
196
byte validatedTrait = HiveDDLUtils.validateConstraint(defaultTrait);
197
byte nonValidatedTrait = HiveDDLUtils.noValidateConstraint(defaultTrait);
198
byte reliableTrait = HiveDDLUtils.relyConstraint(defaultTrait);
199
byte nonReliableTrait = HiveDDLUtils.noRelyConstraint(defaultTrait);
200

201
// Check trait properties
202
boolean requiresEnable = HiveDDLUtils.requireEnableConstraint(defaultTrait);
203
boolean requiresValidate = HiveDDLUtils.requireValidateConstraint(defaultTrait);
204
boolean requiresRely = HiveDDLUtils.requireRelyConstraint(defaultTrait);
205

206
// Encode constraint trait object to byte representation
207
SqlHiveConstraintTrait traitObj = new SqlHiveConstraintTrait(enable, validate, rely);
208
byte encodedTrait = HiveDDLUtils.encodeConstraintTrait(traitObj);
209
```
210

211
## Advanced Constraint Scenarios
212

213
### Primary Key Constraints
214

215
Primary key constraints with various trait combinations:
216

217
```java
218
// Create table with primary key constraint
219
String createTableWithPKSql = """
220
    CREATE TABLE orders (
221
        order_id BIGINT,
222
        customer_id BIGINT,
223
        order_date DATE,
224
        total_amount DECIMAL(10,2),
225
        
226
        -- Primary key with full enforcement
227
        CONSTRAINT pk_order PRIMARY KEY (order_id) ENABLE VALIDATE RELY
228
    )
229
    TBLPROPERTIES (
230
        'hive.pk.constraint.trait' = 'ENABLE_VALIDATE_RELY'
231
    )
232
    """;
233

234
// Programmatic primary key creation
235
HiveTableCreationContext context = new HiveTableCreationContext();
236
context.pkTrait = new SqlHiveConstraintTrait(
237
    SqlHiveConstraintEnable.ENABLE.symbol(pos),
238
    SqlHiveConstraintValidate.VALIDATE.symbol(pos),
239
    SqlHiveConstraintRely.RELY.symbol(pos)
240
);
241
```
242

243
### NOT NULL Constraints
244

245
NOT NULL constraints with trait specifications:
246

247
```java
248
// Create table with NOT NULL constraints
249
String createTableWithNotNullSql = """
250
    CREATE TABLE customer_profile (
251
        customer_id BIGINT NOT NULL ENABLE VALIDATE RELY,
252
        first_name STRING NOT NULL ENABLE NOVALIDATE RELY,
253
        last_name STRING NOT NULL ENABLE NOVALIDATE RELY,
254
        email STRING NOT NULL DISABLE NOVALIDATE NORELY,
255
        phone STRING,
256
        registration_date DATE NOT NULL ENABLE VALIDATE RELY
257
    )
258
    """;
259

260
// Programmatic NOT NULL constraint creation
261
HiveTableCreationContext context = new HiveTableCreationContext();
262

263
// Create NOT NULL traits for multiple columns
264
context.notNullTraits = List.of(
265
    new SqlHiveConstraintTrait(
266
        SqlHiveConstraintEnable.ENABLE.symbol(pos),
267
        SqlHiveConstraintValidate.VALIDATE.symbol(pos),
268
        SqlHiveConstraintRely.RELY.symbol(pos)
269
    ),
270
    new SqlHiveConstraintTrait(
271
        SqlHiveConstraintEnable.ENABLE.symbol(pos),
272
        SqlHiveConstraintValidate.NOVALIDATE.symbol(pos),
273
        SqlHiveConstraintRely.RELY.symbol(pos)
274
    )
275
);
276

277
context.notNullCols = List.of(
278
    new SqlIdentifier("customer_id", pos),
279
    new SqlIdentifier("email", pos)
280
);
281
```
282

283
### Constraint Management Patterns
284

285
```java
286
public class HiveConstraintManager {
287
    
288
    /**
289
     * Creates a constraint trait for different enforcement levels
290
     */
291
    public static SqlHiveConstraintTrait createConstraintTrait(String enforcementLevel, SqlParserPos pos) {
292
        SqlLiteral enable, validate, rely;
293
        
294
        switch (enforcementLevel.toUpperCase()) {
295
            case "STRICT":
296
                // Full enforcement: validate data and enable optimizer reliance
297
                enable = SqlHiveConstraintEnable.ENABLE.symbol(pos);
298
                validate = SqlHiveConstraintValidate.VALIDATE.symbol(pos);
299
                rely = SqlHiveConstraintRely.RELY.symbol(pos);
300
                break;
301
                
302
            case "OPTIMIZER_ONLY":
303
                // Enable for optimizer, but don't validate data
304
                enable = SqlHiveConstraintEnable.ENABLE.symbol(pos);
305
                validate = SqlHiveConstraintValidate.NOVALIDATE.symbol(pos);
306
                rely = SqlHiveConstraintRely.RELY.symbol(pos);
307
                break;
308
                
309
            case "INFORMATIONAL":
310
                // Metadata only, no enforcement or optimization
311
                enable = SqlHiveConstraintEnable.DISABLE.symbol(pos);
312
                validate = SqlHiveConstraintValidate.NOVALIDATE.symbol(pos);
313
                rely = SqlHiveConstraintRely.NORELY.symbol(pos);
314
                break;
315
                
316
            default: // "STANDARD"
317
                // Default Hive behavior: enable but don't validate
318
                enable = SqlHiveConstraintEnable.ENABLE.symbol(pos);
319
                validate = SqlHiveConstraintValidate.NOVALIDATE.symbol(pos);
320
                rely = SqlHiveConstraintRely.RELY.symbol(pos);
321
                break;
322
        }
323
        
324
        return new SqlHiveConstraintTrait(enable, validate, rely);
325
    }
326
    
327
    /**
328
     * Validates constraint trait combinations
329
     */
330
    public static boolean isValidConstraintCombination(SqlHiveConstraintTrait trait) {
331
        // Validation rules:
332
        // 1. Cannot validate disabled constraints
333
        // 2. Cannot rely on disabled constraints
334
        // 3. Should not rely on non-validated constraints (warning, not error)
335
        
336
        if (!trait.isEnable() && trait.isValidate()) {
337
            return false; // Cannot validate disabled constraint
338
        }
339
        
340
        if (!trait.isEnable() && trait.isRely()) {
341
            return false; // Cannot rely on disabled constraint
342
        }
343
        
344
        return true;
345
    }
346
    
347
    /**
348
     * Provides recommendations for constraint traits based on table usage
349
     */
350
    public static String recommendConstraintTrait(String tableType, String workloadType) {
351
        // Recommend constraint traits based on usage patterns
352
        
353
        if ("TRANSACTIONAL".equals(tableType)) {
354
            if ("OLTP".equals(workloadType)) {
355
                return "STRICT"; // Full validation for transactional workloads
356
            } else {
357
                return "STANDARD"; // Enable but don't validate for analytical workloads
358
            }
359
        } else if ("ANALYTICAL".equals(tableType)) {
360
            if ("ETL".equals(workloadType)) {
361
                return "OPTIMIZER_ONLY"; // Help optimizer without validation overhead
362
            } else {
363
                return "INFORMATIONAL"; // Metadata only for ad-hoc queries
364
            }
365
        }
366
        
367
        return "STANDARD"; // Default recommendation
368
    }
369
}
370

371
// Usage examples
372
SqlParserPos pos = SqlParserPos.ZERO;
373

374
// Create strict constraint for critical data
375
SqlHiveConstraintTrait strictTrait = HiveConstraintManager.createConstraintTrait("STRICT", pos);
376
System.out.println("Strict trait - Enable: " + strictTrait.isEnable() + 
377
                   ", Validate: " + strictTrait.isValidate() + 
378
                   ", Rely: " + strictTrait.isRely());
379

380
// Validate constraint combination
381
boolean isValid = HiveConstraintManager.isValidConstraintCombination(strictTrait);
382
System.out.println("Constraint combination is valid: " + isValid);
383

384
// Get recommendation
385
String recommendation = HiveConstraintManager.recommendConstraintTrait("TRANSACTIONAL", "OLTP");
386
System.out.println("Recommended constraint level: " + recommendation);
387
```
388

389
### Constraint Evolution and Migration
390

391
```java
392
// Evolution of constraint enforcement over time
393
public class ConstraintEvolution {
394
    
395
    /**
396
     * Migrates constraints from informational to enforced
397
     */
398
    public void migrateConstraintsToEnforced(String tableName, TableEnvironment tableEnv) {
399
        // Step 1: Start with informational constraints (DISABLE NOVALIDATE NORELY)
400
        String initialConstraintSql = String.format("""
401
            ALTER TABLE %s 
402
            ADD CONSTRAINT pk_temp PRIMARY KEY (id) DISABLE NOVALIDATE NORELY
403
            """, tableName);
404
        
405
        // Step 2: Enable constraint for optimizer (ENABLE NOVALIDATE RELY)
406
        String enableForOptimizerSql = String.format("""
407
            ALTER TABLE %s 
408
            CHANGE CONSTRAINT pk_temp PRIMARY KEY (id) ENABLE NOVALIDATE RELY
409
            """, tableName);
410
        
411
        // Step 3: Enable validation after data cleanup (ENABLE VALIDATE RELY)
412
        String enableValidationSql = String.format("""
413
            ALTER TABLE %s 
414
            CHANGE CONSTRAINT pk_temp PRIMARY KEY (id) ENABLE VALIDATE RELY
415
            """, tableName);
416
        
417
        try {
418
            // Execute migration steps
419
            tableEnv.executeSql(initialConstraintSql);
420
            System.out.println("Step 1: Added informational constraint");
421
            
422
            // Data quality assessment would happen here
423
            
424
            tableEnv.executeSql(enableForOptimizerSql);
425
            System.out.println("Step 2: Enabled constraint for optimizer");
426
            
427
            // Data cleanup and validation would happen here
428
            
429
            tableEnv.executeSql(enableValidationSql);
430
            System.out.println("Step 3: Enabled full constraint validation");
431
            
432
        } catch (Exception e) {
433
            System.err.println("Constraint migration failed: " + e.getMessage());
434
        }
435
    }
436
}
437
```