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.

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.

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.

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.

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.

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.

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.

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.

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).

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).

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.

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:

-- 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:

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:

dotnet test tests/JdeScoping.Database.Tests

See Testing for details.