jdescopingtool/DOCUMENTATION/Database/ExtractionFunctions.md

# Search Criteria Extraction Functions

SQL functions that extract filter values from the `Search.Criteria` JSON column. These functions enable the query builder to pass only a `SearchId` parameter, simplifying the C# to SQL interface.

## Overview

| Type | Count | Purpose |
|------|-------|---------|
| Scalar Functions | 3 | Extract single values (dates, booleans) |
| Table-Valued Functions | 8 | Extract arrays and object collections |
| Validation Procedure | 1 | Pre-flight validation with error codes |

## Scalar Functions

### fn_GetSearchMinimumDt

Extracts the minimum date filter value.

```sql
CREATE FUNCTION dbo.fn_GetSearchMinimumDt(@SearchId INT)
RETURNS DATETIME2(7)
```

**JSON Path**: `$.MinimumDt`

**Returns**: DATETIME2 value or NULL if not found/invalid

### fn_GetSearchMaximumDt

Extracts the maximum date filter value.

```sql
CREATE FUNCTION dbo.fn_GetSearchMaximumDt(@SearchId INT)
RETURNS DATETIME2(7)
```

**JSON Path**: `$.MaximumDt`

**Returns**: DATETIME2 value or NULL if not found/invalid

### fn_GetSearchExtractMisData

Extracts the MIS data extraction flag.

```sql
CREATE FUNCTION dbo.fn_GetSearchExtractMisData(@SearchId INT)
RETURNS BIT
```

**JSON Path**: `$.ExtractMisData`

**Returns**: 1 (true), 0 (false), or NULL if not found/invalid

## Table-Valued Functions (Simple Arrays)

### fn_GetSearchWorkOrders

Extracts work order number filter values.

```sql
CREATE FUNCTION dbo.fn_GetSearchWorkOrders(@SearchId INT)
RETURNS TABLE
AS RETURN (
    SELECT j.WorkOrderNumber
    FROM ... OPENJSON(..., '$.WorkOrderNumbers') WITH (WorkOrderNumber BIGINT '$') j
)
```

**JSON Path**: `$.WorkOrderNumbers`

**Returns**: Table with `WorkOrderNumber BIGINT` column

### fn_GetSearchItemNumbers

Extracts item number filter values.

```sql
CREATE FUNCTION dbo.fn_GetSearchItemNumbers(@SearchId INT)
RETURNS TABLE
```

**JSON Path**: `$.ItemNumbers`

**Returns**: Table with `ItemNumber VARCHAR(128)` column

### fn_GetSearchProfitCenters

Extracts profit center filter values.

```sql
CREATE FUNCTION dbo.fn_GetSearchProfitCenters(@SearchId INT)
RETURNS TABLE
```

**JSON Path**: `$.ProfitCenters`

**Returns**: Table with `Code VARCHAR(12)` column

### fn_GetSearchWorkCenters

Extracts work center filter values.

```sql
CREATE FUNCTION dbo.fn_GetSearchWorkCenters(@SearchId INT)
RETURNS TABLE
```

**JSON Path**: `$.WorkCenters`

**Returns**: Table with `Code VARCHAR(12)` column

### fn_GetSearchOperatorIDs

Extracts operator ID filter values.

```sql
CREATE FUNCTION dbo.fn_GetSearchOperatorIDs(@SearchId INT)
RETURNS TABLE
```

**JSON Path**: `$.OperatorIDs`

**Returns**: Table with `OperatorID VARCHAR(128)` column

## Table-Valued Functions (Complex Objects)

### fn_GetSearchComponentLots

Extracts component lot filter values (lot/item pairs).

```sql
CREATE FUNCTION dbo.fn_GetSearchComponentLots(@SearchId INT)
RETURNS TABLE
AS RETURN (
    SELECT j.LotNumber, j.ItemNumber
    FROM ... OPENJSON(..., '$.ComponentLotNumbers') WITH (
        LotNumber VARCHAR(30) '$.LotNumber',
        ItemNumber VARCHAR(128) '$.ItemNumber'
    ) j
)
```

**JSON Path**: `$.ComponentLotNumbers`

**Returns**: Table with `LotNumber VARCHAR(30)`, `ItemNumber VARCHAR(128)` columns

### fn_GetSearchPartOperations

Extracts part operation filter values (item/operation/MIS combinations).

```sql
CREATE FUNCTION dbo.fn_GetSearchPartOperations(@SearchId INT)
RETURNS TABLE
AS RETURN (
    SELECT j.ItemNumber, j.OperationNumber, j.MisNumber, j.MisRevision
    FROM ... OPENJSON(..., '$.PartOperations') WITH (
        ItemNumber VARCHAR(128) '$.ItemNumber',
        OperationNumber VARCHAR(10) '$.OperationNumber',
        MisNumber VARCHAR(10) '$.MisNumber',
        MisRevision VARCHAR(10) '$.MisRevision'
    ) j
)
```

**JSON Path**: `$.PartOperations`

**Returns**: Table with `ItemNumber`, `OperationNumber`, `MisNumber`, `MisRevision` columns

## Validation Procedure

### usp_ValidateSearchCriteria

Validates that a search exists and has valid JSON criteria.

```sql
CREATE PROCEDURE dbo.usp_ValidateSearchCriteria(@SearchId INT)
```

**Error Codes**:

| Code | Condition | Message |
|------|-----------|---------|
| 50001 | Search not found | "Search ID {id} not found" |
| 50002 | Criteria NULL or empty | "Search ID {id} has no criteria" |
| 50003 | Invalid JSON | "Search ID {id} has invalid JSON" |

**Usage**:
```sql
-- Throws on validation failure
EXEC dbo.usp_ValidateSearchCriteria @SearchId = 123;
```

## Error Handling

All extraction functions handle errors gracefully:

- **Scalar functions**: Return NULL for missing search, NULL criteria, or invalid JSON
- **Table-valued functions**: Return empty result set for missing search, NULL criteria, or invalid JSON
- **Validation procedure**: Throws errors via `THROW` statement for calling code to handle

## Design Pattern

Functions use a CTE pattern to pre-filter valid JSON before calling OPENJSON:

```sql
WITH ValidSearch AS (
    SELECT Criteria
    FROM dbo.Search
    WHERE ID = @SearchId
      AND Criteria IS NOT NULL
      AND ISJSON(Criteria) = 1
)
SELECT ...
FROM ValidSearch s
CROSS APPLY OPENJSON(s.Criteria, '$.ArrayPath') ...
```

This pattern prevents OPENJSON from running on invalid JSON, which would cause runtime errors.

## Migration Scripts

| Script | Contents |
|--------|----------|
| `045_CreateScalarExtractionFunctions.sql` | Scalar functions |
| `046_CreateSimpleTableFunctions.sql` | Simple array TVFs |
| `047_CreateComplexTableFunctions.sql` | Complex object TVFs |
| `048_CreateValidateSearchCriteriaProcedure.sql` | Validation procedure |

## Testing

82 tests in `JdeScoping.Database.Tests` verify function behavior:

```bash
dotnet test tests/JdeScoping.Database.Tests
```

See [Testing](../Architecture/Testing.md) for details.