rez_core 7.1.21 → 7.1.22

package/docs/FILTER2_FLATJSON_GUIDE.md

@@ -1,974 +1,974 @@
-# Filter2.0 FlatJson Support Guide
-
-## Overview
-
-The Filter2Service now supports **FlatJson** entities, which store all attribute data in a JSON column within the `entity_json` table. This allows for flexible schema-less data storage while maintaining full filtering capabilities.
-
-## FlatJson Architecture
-
-### Database Structure
-
-```sql
--- entity_json table structure
-CREATE TABLE entity_json (
-  id BIGSERIAL PRIMARY KEY,
-  entity_type VARCHAR(50) NOT NULL,
-  entity_id BIGINT NOT NULL,
-  entity_json JSONB NOT NULL,  -- All attributes stored here
-  created_date TIMESTAMP,
-  modified_date TIMESTAMP,
-  created_by BIGINT,
-  modified_by BIGINT,
-  UNIQUE(entity_type, entity_id)
-);
-
--- Example data
-{
-  "id": 1,
-  "entity_type": "LEAD",
-  "entity_id": 12345,
-  "entity_json": {
-    "name": "John Doe",
-    "email": "john@example.com",
-    "phone": "1234567890",
-    "status": "ACTIVE",
-    "salary": 75000,
-    "created_date": "2024-01-15"
-  }
-}
-```
-
-### How It Works
-
-1. **Regular Entities**: Data stored in dedicated tables (e.g., `frm_lead`)
-2. **FlatJson Entities**: Data stored in `entity_json` table with JSON column
-3. **Attribute Metadata**: `findAttributesByMappedEntityType()` returns different attributes based on entity storage type
-
-## Using FlatJson Filters
-
-### Basic Usage
-
-```typescript
-import { Filter2Service } from './filter/service/filter2.service';
-
-@Injectable()
-export class LeadService {
-  constructor(
-    private readonly filter2Service: Filter2Service,
-  ) {}
-
-  async getLeadsWithFlatJson(userData: any) {
-    return await this.filter2Service.GetFilterData(
-      'LEAD',
-      [
-        {
-          filter_attribute: 'name',
-          filter_operator: 'contains',
-          filter_value: 'John',
-          filter_entity_type: 'LEAD',
-        },
-        {
-          filter_attribute: 'status',
-          filter_operator: 'equal',
-          filter_value: 'ACTIVE',
-          filter_entity_type: 'LEAD',
-        },
-      ],
-      [{ column: 'created_date', order: 'DESC' }],
-      ['id', 'name', 'email', 'status'],
-      [],
-      { page: 1, size: 20 },
-      userData,
-      true, // ← flatJson = true
-      'entity_json', // ← JSON column name
-    );
-  }
-}
-```
-
-### Generated SQL
-
-**With flatJson = true:**
-```sql
-SELECT
-  e.entity_id AS id,
-  e.entity_json->>'name' AS name,
-  e.entity_json->>'email' AS email,
-  e.entity_json->>'status' AS status
-FROM rez.entity_json AS e
-WHERE e.entity_type = 'LEAD'
-  AND LOWER(e.entity_json->>'name') LIKE '%john%'
-  AND e.entity_json->>'status' = 'ACTIVE'
-ORDER BY e.entity_json->>'created_date' DESC
-LIMIT 20 OFFSET 0
-```
-
-**Without flatJson (regular):**
-```sql
-SELECT
-  e.id,
-  e.name,
-  e.email,
-  e.status
-FROM rez.frm_lead AS e
-WHERE LOWER(e.name) LIKE '%john%'
-  AND e.status = 'ACTIVE'
-ORDER BY e.created_date DESC
-LIMIT 20 OFFSET 0
-```
-
-## Filter Examples
-
-### Example 1: Text Filter
-
-```typescript
-const result = await this.filter2Service.GetFilterData(
-  'LEAD',
-  [
-    {
-      filter_attribute: 'name',
-      filter_operator: 'contains',
-      filter_value: 'John',
-      filter_entity_type: 'LEAD',
-    },
-  ],
-  [],
-  [],
-  [],
-  undefined,
-  userData,
-  true, // flatJson
-  'entity_json',
-);
-
-// Generated SQL:
-// WHERE LOWER(e.entity_json->>'name') LIKE '%john%'
-```
-
-### Example 2: Number Filter
-
-```typescript
-const result = await this.filter2Service.GetFilterData(
-  'LEAD',
-  [
-    {
-      filter_attribute: 'salary',
-      filter_operator: 'greater_than',
-      filter_value: 50000,
-      filter_entity_type: 'LEAD',
-    },
-  ],
-  [],
-  [],
-  [],
-  undefined,
-  userData,
-  true,
-  'entity_json',
-);
-
-// Generated SQL:
-// WHERE (e.entity_json->>'salary')::numeric > 50000
-```
-
-### Example 3: Date Filter
-
-```typescript
-const result = await this.filter2Service.GetFilterData(
-  'LEAD',
-  [
-    {
-      filter_attribute: 'created_date',
-      filter_operator: 'after',
-      filter_value: '2024-01-01',
-      filter_entity_type: 'LEAD',
-    },
-  ],
-  [],
-  [],
-  [],
-  undefined,
-  userData,
-  true,
-  'entity_json',
-);
-
-// Generated SQL (dates stored as millisecond timestamps):
-// WHERE DATE(to_timestamp((e.entity_json->>'created_date')::bigint / 1000.0)) > '2024-01-01'
-```
-
-### Example 4: Multiple Filters
-
-```typescript
-const result = await this.filter2Service.GetFilterData(
-  'LEAD',
-  [
-    {
-      filter_attribute: 'name',
-      filter_operator: 'contains',
-      filter_value: 'John',
-      filter_entity_type: 'LEAD',
-    },
-    {
-      filter_attribute: 'status',
-      filter_operator: 'equal',
-      filter_value: 'ACTIVE',
-      filter_entity_type: 'LEAD',
-    },
-    {
-      filter_attribute: 'salary',
-      filter_operator: 'greater_than',
-      filter_value: 50000,
-      filter_entity_type: 'LEAD',
-    },
-  ],
-  [],
-  [],
-  [],
-  undefined,
-  userData,
-  true,
-  'entity_json',
-);
-
-// Generated SQL:
-// WHERE e.entity_type = 'LEAD'
-//   AND LOWER(e.entity_json->>'name') LIKE '%john%'
-//   AND e.entity_json->>'status' = 'ACTIVE'
-//   AND (e.entity_json->>'salary')::numeric > 50000
-```
-
-### Example 5: With Pagination and Sorting
-
-```typescript
-const result = await this.filter2Service.GetFilterData(
-  'LEAD',
-  [
-    {
-      filter_attribute: 'status',
-      filter_operator: 'equal',
-      filter_value: 'ACTIVE',
-      filter_entity_type: 'LEAD',
-    },
-  ],
-  [
-    { column: 'name', order: 'ASC' },
-    { column: 'created_date', order: 'DESC' },
-  ],
-  ['id', 'name', 'email', 'status', 'created_date'],
-  [],
-  { page: 2, size: 25 },
-  userData,
-  true,
-  'entity_json',
-);
-
-// Generated SQL:
-// SELECT
-//   e.entity_id AS id,
-//   e.entity_json->>'name' AS name,
-//   e.entity_json->>'email' AS email,
-//   e.entity_json->>'status' AS status,
-//   e.entity_json->>'created_date' AS created_date
-// FROM rez.entity_json AS e
-// WHERE e.entity_type = 'LEAD'
-//   AND e.entity_json->>'status' = 'ACTIVE'
-// ORDER BY e.entity_json->>'name' ASC, e.entity_json->>'created_date' DESC
-// LIMIT 25 OFFSET 25
-```
-
-### Example 6: Filter by IDs
-
-```typescript
-const result = await this.filter2Service.GetFilterData(
-  'LEAD',
-  [],
-  [],
-  [],
-  [101, 102, 103, 104, 105], // Specific entity IDs
-  undefined,
-  userData,
-  true,
-  'entity_json',
-);
-
-// Generated SQL:
-// WHERE e.entity_type = 'LEAD'
-//   AND e.entity_id::text = ANY('{101,102,103,104,105}')
-```
-
-### Example 7: Using GetFilterDataInternal
-
-```typescript
-const result = await this.filter2Service.GetFilterDataInternal(
-  'LEAD',
-  'MY_SAVED_FILTER', // Saved filter code
-  [
-    {
-      filter_attribute: 'status',
-      filter_operator: 'equal',
-      filter_value: 'ACTIVE',
-      filter_entity_type: 'LEAD',
-    },
-  ],
-  ['id', 'name', 'email'],
-  [],
-  userData,
-  true, // flatJson
-  'entity_json',
-);
-```
-
-### Example 8: Using GetFilterDataForListing
-
-```typescript
-const result = await this.filter2Service.GetFilterDataForListing(
-  'LEAD',
-  [
-    {
-      filter_attribute: 'name',
-      filter_operator: 'contains',
-      filter_value: 'Test',
-      filter_entity_type: 'LEAD',
-    },
-  ],
-  undefined, // No saved filter
-  [],
-  { column: 'name', order: 'ASC' },
-  { page: 1, size: 20 },
-  userData,
-  true, // flatJson
-  'entity_json',
-);
-
-// Automatically:
-// 1. Fetches layout preferences
-// 2. Uses columns from layout
-// 3. Uses sorting from layout
-// 4. Queries entity_json table
-```
-
-### Example 9: Multiselect Filter (Array Values)
-
-```typescript
-// Sample data in entity_json:
-// {
-//   "tags": ["important", "urgent", "follow-up"],
-//   "categories": ["sales", "marketing"]
-// }
-
-// Filter leads that have "important" tag
-const result = await this.filter2Service.GetFilterData(
-  'LEAD',
-  [
-    {
-      filter_attribute: 'tags',
-      filter_operator: 'contains', // or 'equal'
-      filter_value: 'important',
-      filter_entity_type: 'LEAD',
-    },
-  ],
-  [],
-  [],
-  [],
-  { page: 1, size: 20 },
-  userData,
-  true,
-  'entity_json',
-);
-
-// Generated SQL:
-// WHERE (e.entity_json->>'tags')::jsonb @> '["important"]'::jsonb
-
-// Filter leads that have ANY of these tags
-const resultAny = await this.filter2Service.GetFilterData(
-  'LEAD',
-  [
-    {
-      filter_attribute: 'tags',
-      filter_operator: 'contains_any',
-      filter_value: ['important', 'urgent'], // or 'important,urgent'
-      filter_entity_type: 'LEAD',
-    },
-  ],
-  [],
-  [],
-  [],
-  { page: 1, size: 20 },
-  userData,
-  true,
-  'entity_json',
-);
-
-// Generated SQL:
-// WHERE (e.entity_json->>'tags')::jsonb ?| ARRAY['important', 'urgent']
-
-// Filter leads that have ALL of these tags
-const resultAll = await this.filter2Service.GetFilterData(
-  'LEAD',
-  [
-    {
-      filter_attribute: 'tags',
-      filter_operator: 'contains_all',
-      filter_value: ['important', 'urgent'],
-      filter_entity_type: 'LEAD',
-    },
-  ],
-  [],
-  [],
-  [],
-  { page: 1, size: 20 },
-  userData,
-  true,
-  'entity_json',
-);
-
-// Generated SQL:
-// WHERE (e.entity_json->>'tags')::jsonb ?& ARRAY['important', 'urgent']
-```
-
-### Example 10: Date Filter (Millisecond Timestamps)
-
-```typescript
-// Sample data in entity_json:
-// {
-//   "created_date": 1704067200000,  // Jan 1, 2024 00:00:00 in milliseconds
-//   "modified_date": 1706745600000  // Feb 1, 2024 00:00:00 in milliseconds
-// }
-
-// Filter leads created after Jan 1, 2024
-const result = await this.filter2Service.GetFilterData(
-  'LEAD',
-  [
-    {
-      filter_attribute: 'created_date',
-      filter_operator: 'after',
-      filter_value: '2024-01-01',
-      filter_entity_type: 'LEAD',
-    },
-  ],
-  [],
-  [],
-  [],
-  { page: 1, size: 20 },
-  userData,
-  true,
-  'entity_json',
-);
-
-// Generated SQL (automatically converts milliseconds to timestamp):
-// WHERE DATE(to_timestamp((e.entity_json->>'created_date')::bigint / 1000.0)) > '2024-01-01'
-
-// Filter leads created between two dates
-const resultBetween = await this.filter2Service.GetFilterData(
-  'LEAD',
-  [
-    {
-      filter_attribute: 'created_date',
-      filter_operator: 'between',
-      filter_value: '2024-01-01,2024-12-31', // or ['2024-01-01', '2024-12-31']
-      filter_entity_type: 'LEAD',
-    },
-  ],
-  [],
-  [],
-  [],
-  { page: 1, size: 20 },
-  userData,
-  true,
-  'entity_json',
-);
-
-// Generated SQL:
-// WHERE DATE(to_timestamp((e.entity_json->>'created_date')::bigint / 1000.0))
-//       BETWEEN '2024-01-01' AND '2024-12-31'
-```
-
-### Example 11: Complex Filter (Mixed Data Types)
-
-```typescript
-// Sample data in entity_json:
-// {
-//   "name": "John Doe",
-//   "email": "john@example.com",
-//   "salary": 75000,
-//   "tags": ["important", "vip"],
-//   "created_date": 1704067200000,
-//   "status": ["ACTIVE"]
-// }
-
-const result = await this.filter2Service.GetFilterData(
-  'LEAD',
-  [
-    {
-      filter_attribute: 'name',
-      filter_operator: 'contains',
-      filter_value: 'John',
-      filter_entity_type: 'LEAD',
-    },
-    {
-      filter_attribute: 'salary',
-      filter_operator: 'greater_than',
-      filter_value: 50000,
-      filter_entity_type: 'LEAD',
-    },
-    {
-      filter_attribute: 'tags',
-      filter_operator: 'contains',
-      filter_value: 'vip',
-      filter_entity_type: 'LEAD',
-    },
-    {
-      filter_attribute: 'created_date',
-      filter_operator: 'after',
-      filter_value: '2024-01-01',
-      filter_entity_type: 'LEAD',
-    },
-    {
-      filter_attribute: 'status',
-      filter_operator: 'equal',
-      filter_value: 'ACTIVE',
-      filter_entity_type: 'LEAD',
-    },
-  ],
-  [{ column: 'created_date', order: 'DESC' }],
-  ['id', 'name', 'email', 'salary', 'tags', 'status'],
-  [],
-  { page: 1, size: 20 },
-  userData,
-  true,
-  'entity_json',
-);
-
-// Generated SQL:
-// SELECT
-//   e.entity_id AS id,
-//   e.entity_json->>'name' AS name,
-//   e.entity_json->>'email' AS email,
-//   e.entity_json->>'salary' AS salary,
-//   e.entity_json->>'tags' AS tags,
-//   e.entity_json->>'status' AS status
-// FROM rez.entity_json AS e
-// WHERE e.entity_type = 'LEAD'
-//   AND LOWER(e.entity_json->>'name') LIKE '%john%'
-//   AND (e.entity_json->>'salary')::numeric > 50000
-//   AND (e.entity_json->>'tags')::jsonb @> '["vip"]'::jsonb
-//   AND DATE(to_timestamp((e.entity_json->>'created_date')::bigint / 1000.0)) > '2024-01-01'
-//   AND (e.entity_json->>'status')::jsonb @> '["ACTIVE"]'::jsonb
-// ORDER BY to_timestamp((e.entity_json->>'created_date')::bigint / 1000.0) DESC
-// LIMIT 20 OFFSET 0
-```
-
-## Supported Operators
-
-### Text Operators
-- `contains` - Case-insensitive partial match
-- `equal` - Exact match
-- `not_equal` - Not equal
-- `empty` - IS NULL or empty string
-- `not_empty` - IS NOT NULL and not empty string
-
-**SQL Examples:**
-```sql
--- contains
-LOWER(e.entity_json->>'name') LIKE '%john%'
-
--- equal
-e.entity_json->>'name' = 'John Doe'
-
--- empty
-(e.entity_json->>'name' IS NULL OR e.entity_json->>'name' = '')
-```
-
-### Number Operators
-- `equal`
-- `not_equal`
-- `greater_than`
-- `less_than`
-- `greater_than_qual_to`
-- `less_than_qual_to`
-- `empty`
-- `not_empty`
-
-**SQL Examples:**
-```sql
--- greater_than
-(e.entity_json->>'salary')::numeric > 50000
-
--- less_than_qual_to
-(e.entity_json->>'age')::numeric <= 30
-```
-
-### Date Operators
-- `equal` / `is`
-- `before` / `is_before`
-- `after` / `is_after`
-- `is_on_or_before`
-- `is_on_or_after`
-- `between`
-- `empty`
-- `not_empty`
-
-**Note:** Dates are stored as timestamp milliseconds in flatjson.
-
-**SQL Examples:**
-```sql
--- after (with millisecond timestamp conversion)
-DATE(to_timestamp((e.entity_json->>'created_date')::bigint / 1000.0)) > '2024-01-01'
-
--- between (with millisecond timestamp conversion)
-DATE(to_timestamp((e.entity_json->>'created_date')::bigint / 1000.0)) BETWEEN '2024-01-01' AND '2024-12-31'
-
--- Millisecond timestamp conversion:
--- to_timestamp(milliseconds::bigint / 1000.0) converts ms to timestamp
-```
-
-### Select/Multiselect Operators
-- `equal` / `contains` - Check if array contains a specific value
-- `not_equal` / `not_contains` - Check if array does NOT contain a specific value
-- `contains_any` - Check if array contains ANY of the provided values
-- `contains_all` - Check if array contains ALL of the provided values
-- `empty` - Check if null, empty string, or empty array
-- `not_empty` - Check if not null and not empty array
-
-**Note:** Multiselect values are stored as JSON arrays: `["value1", "value2"]`
-
-**SQL Examples:**
-```sql
--- equal/contains (single value in array)
-(e.entity_json->>'status')::jsonb @> '["ACTIVE"]'::jsonb
-
--- not_equal/not_contains
-NOT ((e.entity_json->>'status')::jsonb @> '["ACTIVE"]'::jsonb)
-
--- contains_any (using ?| operator)
-(e.entity_json->>'tags')::jsonb ?| ARRAY['important', 'urgent']
-
--- contains_all (using ?& operator)
-(e.entity_json->>'tags')::jsonb ?& ARRAY['important', 'urgent']
-
--- empty (null, empty string, or empty array)
-(e.entity_json->>'tags' IS NULL OR e.entity_json->>'tags' = '' OR jsonb_array_length((e.entity_json->>'tags')::jsonb) = 0)
-
--- PostgreSQL JSONB Operators used:
--- @> : containment operator (left contains right)
--- ?| : does the array contain any of these keys/values
--- ?& : does the array contain all of these keys/values
-```
-
-## Comparison: Regular vs FlatJson
-
-### Data Storage
-
-| Aspect | Regular Entity | FlatJson Entity |
-|--------|----------------|-----------------|
-| Table | Dedicated (e.g., `frm_lead`) | `entity_json` |
-| Schema | Fixed columns | Flexible JSON |
-| Attributes | Table columns | JSON properties |
-| Storage Type | DB_COL or EAV | JSON |
-| Flexibility | Low (schema change needed) | High (no schema change) |
-
-### Query Performance
-
-| Operation | Regular | FlatJson |
-|-----------|---------|----------|
-| Simple filter | Fast | Fast |
-| Multiple filters | Fast | Moderate |
-| Sorting | Fast (indexed) | Moderate (JSON ops) |
-| Pagination | Fast | Fast |
-| Full-text search | Fast (with indexes) | Slower |
-
-### When to Use FlatJson
-
-✅ **Use FlatJson when:**
-- Schema changes frequently
-- Attributes are dynamic per entity
-- Rapid prototyping needed
-- Data structure varies by tenant
-- Flexible data model required
-
-❌ **Avoid FlatJson when:**
-- High-performance queries needed
-- Complex joins required
-- Large datasets (millions of rows)
-- Frequent aggregations
-- Need database-level constraints
-
-## PostgreSQL JSON Operators
-
-The FlatJson implementation uses PostgreSQL JSON operators:
-
-| Operator | Description | Example |
-|----------|-------------|---------|
-| `->` | Get JSON object field | `entity_json->'name'` |
-| `->>` | Get JSON object field as text | `entity_json->>'name'` |
-| `::numeric` | Cast to numeric | `(entity_json->>'salary')::numeric` |
-| `::jsonb` | Cast to JSONB | `(entity_json->>'tags')::jsonb` |
-| `::bigint` | Cast to bigint | `(entity_json->>'created_date')::bigint` |
-| `to_timestamp()` | Convert milliseconds to timestamp | `to_timestamp(ms::bigint / 1000.0)` |
-| `DATE()` | Extract date | `DATE(to_timestamp(ms::bigint / 1000.0))` |
-| `@>` | JSONB containment operator | `'["a","b"]'::jsonb @> '["a"]'::jsonb` |
-| `?|` | JSONB contains ANY operator | `'["a","b"]'::jsonb ?| ARRAY['a','c']` |
-| `?&` | JSONB contains ALL operator | `'["a","b"]'::jsonb ?& ARRAY['a','b']` |
-| `jsonb_array_length()` | Get JSONB array length | `jsonb_array_length('["a","b"]'::jsonb)` |
-
-## Data Format Considerations
-
-### Date/Time Storage
-
-**Important:** Dates and times in FlatJson are stored as **timestamp milliseconds** (not regular timestamps).
-
-**Example Data:**
-```json
-{
-  "entity_json": {
-    "created_date": 1704067200000,  // Jan 1, 2024 00:00:00 in milliseconds
-    "modified_date": 1706745600000
-  }
-}
-```
-
-**Filter Implementation:**
-The service automatically converts millisecond timestamps to proper timestamps:
-```sql
--- Conversion formula:
-to_timestamp((e.entity_json->>'created_date')::bigint / 1000.0)
-
--- Usage in filter:
-DATE(to_timestamp((e.entity_json->>'created_date')::bigint / 1000.0)) > '2024-01-01'
-```
-
-### Multiselect Storage
-
-**Important:** Multiselect values in FlatJson are stored as **JSON arrays**, not strings.
-
-**Example Data:**
-```json
-{
-  "entity_json": {
-    "tags": ["important", "urgent", "follow-up"],
-    "status": ["ACTIVE"],
-    "categories": []
-  }
-}
-```
-
-**Filter Implementation:**
-The service uses PostgreSQL JSONB operators for array operations:
-```sql
--- Check if array contains a value:
-(e.entity_json->>'tags')::jsonb @> '["important"]'::jsonb
-
--- Check if array contains ANY values:
-(e.entity_json->>'tags')::jsonb ?| ARRAY['important', 'urgent']
-
--- Check if array contains ALL values:
-(e.entity_json->>'tags')::jsonb ?& ARRAY['important', 'urgent']
-
--- Check if array is empty:
-jsonb_array_length((e.entity_json->>'tags')::jsonb) = 0
-```
-
-### Single-Select Storage
-
-Single-select values can be stored as either strings or single-element arrays:
-```json
-{
-  "entity_json": {
-    "status": ["ACTIVE"],  // Array format (recommended for consistency)
-    "type": "LEAD"         // String format (also supported)
-  }
-}
-```
-
-**Best Practice:** Store all select fields as arrays for consistency, even single-select fields.
-
-## Performance Optimization
-
-### 1. Create GIN Index on JSON Column
-
-```sql
-CREATE INDEX idx_entity_json_gin
-ON entity_json USING GIN (entity_json);
-```
-
-### 2. Create Expression Index for Common Filters
-
-```sql
--- Index for name searches
-CREATE INDEX idx_entity_json_name
-ON entity_json ((entity_json->>'name'));
-
--- Index for status filters
-CREATE INDEX idx_entity_json_status
-ON entity_json ((entity_json->>'status'));
-
--- Index for date filters
-CREATE INDEX idx_entity_json_created_date
-ON entity_json (((entity_json->>'created_date')::timestamp));
-```
-
-### 3. Partition by Entity Type
-
-```sql
-CREATE TABLE entity_json_lead PARTITION OF entity_json
-FOR VALUES IN ('LEAD');
-
-CREATE TABLE entity_json_contact PARTITION OF entity_json
-FOR VALUES IN ('CONTACT');
-```
-
-### 4. Use Specific Column Selection
-
-```typescript
-// ❌ Bad: Returns entire JSON
-const bad = await filter2Service.GetFilterData(
-  'LEAD', [], [], [], [], undefined, userData, true, 'entity_json'
-);
-
-// ✅ Good: Returns only needed columns
-const good = await filter2Service.GetFilterData(
-  'LEAD', [], [], ['id', 'name', 'email'], [], undefined, userData, true, 'entity_json'
-);
-```
-
-## Migration from Regular to FlatJson
-
-### Step 1: Copy Data to entity_json
-
-```sql
-INSERT INTO entity_json (entity_type, entity_id, entity_json, created_date, modified_date)
-SELECT
-  'LEAD' AS entity_type,
-  id AS entity_id,
-  jsonb_build_object(
-    'name', name,
-    'email', email,
-    'phone', phone,
-    'status', status,
-    'salary', salary
-  ) AS entity_json,
-  created_date,
-  modified_date
-FROM frm_lead;
-```
-
-### Step 2: Update Application Code
-
-```typescript
-// Old way (regular table)
-const oldResult = await filter2Service.GetFilterData(
-  'LEAD',
-  filters,
-  sortColumns,
-  columns,
-  [],
-  pagination,
-  userData,
-  false, // flatJson = false
-);
-
-// New way (flatjson)
-const newResult = await filter2Service.GetFilterData(
-  'LEAD',
-  filters,
-  sortColumns,
-  columns,
-  [],
-  pagination,
-  userData,
-  true, // flatJson = true
-  'entity_json',
-);
-```
-
-### Step 3: Verify Data
-
-```typescript
-// Test query
-const test = await filter2Service.GetFilterData(
-  'LEAD',
-  [],
-  [],
-  ['id', 'name', 'email'],
-  [1, 2, 3], // Test with specific IDs
-  undefined,
-  userData,
-  true,
-  'entity_json',
-);
-
-console.log(test.entity_list);
-```
-
-## Error Handling
-
-### Invalid JSON Path
-
-```typescript
-try {
-  const result = await filter2Service.GetFilterData(
-    'LEAD',
-    [
-      {
-        filter_attribute: 'nonexistent_field',
-        filter_operator: 'equal',
-        filter_value: 'test',
-        filter_entity_type: 'LEAD',
-      },
-    ],
-    [],
-    [],
-    [],
-    undefined,
-    userData,
-    true,
-    'entity_json',
-  );
-} catch (error) {
-  // Handle gracefully - will return NULL for non-existent fields
-  console.log('Field not found in JSON');
-}
-```
-
-### Type Casting Errors
-
-```typescript
-// Attempting to cast non-numeric value to numeric
-try {
-  const result = await filter2Service.GetFilterData(
-    'LEAD',
-    [
-      {
-        filter_attribute: 'name', // Text field
-        filter_operator: 'greater_than', // Numeric operator
-        filter_value: 100,
-        filter_entity_type: 'LEAD',
-      },
-    ],
-    [],
-    [],
-    [],
-    undefined,
-    userData,
-    true,
-    'entity_json',
-  );
-} catch (error) {
-  console.error('Type casting error:', error.message);
-  // "invalid input syntax for type numeric"
-}
-```
-
-## Summary
-
-FlatJson support in Filter2Service provides:
-
-✅ **Flexible Schema** - No database migrations needed for new attributes
-✅ **Full Filter Support** - All operators work on JSON fields
-✅ **PostgreSQL JSON Operators** - Leverages native JSON capabilities
-✅ **Pagination & Sorting** - Works just like regular queries
-✅ **Layout Preferences** - Integrates with existing UI preferences
-✅ **Performance** - Optimized with GIN indexes and expression indexes
-
-Use flatJson when you need schema flexibility. Use regular tables when you need maximum performance.
+# Filter2.0 FlatJson Support Guide
+
+## Overview
+
+The Filter2Service now supports **FlatJson** entities, which store all attribute data in a JSON column within the `entity_json` table. This allows for flexible schema-less data storage while maintaining full filtering capabilities.
+
+## FlatJson Architecture
+
+### Database Structure
+
+```sql
+-- entity_json table structure
+CREATE TABLE entity_json (
+  id BIGSERIAL PRIMARY KEY,
+  entity_type VARCHAR(50) NOT NULL,
+  entity_id BIGINT NOT NULL,
+  entity_json JSONB NOT NULL,  -- All attributes stored here
+  created_date TIMESTAMP,
+  modified_date TIMESTAMP,
+  created_by BIGINT,
+  modified_by BIGINT,
+  UNIQUE(entity_type, entity_id)
+);
+
+-- Example data
+{
+  "id": 1,
+  "entity_type": "LEAD",
+  "entity_id": 12345,
+  "entity_json": {
+    "name": "John Doe",
+    "email": "john@example.com",
+    "phone": "1234567890",
+    "status": "ACTIVE",
+    "salary": 75000,
+    "created_date": "2024-01-15"
+  }
+}
+```
+
+### How It Works
+
+1. **Regular Entities**: Data stored in dedicated tables (e.g., `frm_lead`)
+2. **FlatJson Entities**: Data stored in `entity_json` table with JSON column
+3. **Attribute Metadata**: `findAttributesByMappedEntityType()` returns different attributes based on entity storage type
+
+## Using FlatJson Filters
+
+### Basic Usage
+
+```typescript
+import { Filter2Service } from './filter/service/filter2.service';
+
+@Injectable()
+export class LeadService {
+  constructor(
+    private readonly filter2Service: Filter2Service,
+  ) {}
+
+  async getLeadsWithFlatJson(userData: any) {
+    return await this.filter2Service.GetFilterData(
+      'LEAD',
+      [
+        {
+          filter_attribute: 'name',
+          filter_operator: 'contains',
+          filter_value: 'John',
+          filter_entity_type: 'LEAD',
+        },
+        {
+          filter_attribute: 'status',
+          filter_operator: 'equal',
+          filter_value: 'ACTIVE',
+          filter_entity_type: 'LEAD',
+        },
+      ],
+      [{ column: 'created_date', order: 'DESC' }],
+      ['id', 'name', 'email', 'status'],
+      [],
+      { page: 1, size: 20 },
+      userData,
+      true, // ← flatJson = true
+      'entity_json', // ← JSON column name
+    );
+  }
+}
+```
+
+### Generated SQL
+
+**With flatJson = true:**
+```sql
+SELECT
+  e.entity_id AS id,
+  e.entity_json->>'name' AS name,
+  e.entity_json->>'email' AS email,
+  e.entity_json->>'status' AS status
+FROM rez.entity_json AS e
+WHERE e.entity_type = 'LEAD'
+  AND LOWER(e.entity_json->>'name') LIKE '%john%'
+  AND e.entity_json->>'status' = 'ACTIVE'
+ORDER BY e.entity_json->>'created_date' DESC
+LIMIT 20 OFFSET 0
+```
+
+**Without flatJson (regular):**
+```sql
+SELECT
+  e.id,
+  e.name,
+  e.email,
+  e.status
+FROM rez.frm_lead AS e
+WHERE LOWER(e.name) LIKE '%john%'
+  AND e.status = 'ACTIVE'
+ORDER BY e.created_date DESC
+LIMIT 20 OFFSET 0
+```
+
+## Filter Examples
+
+### Example 1: Text Filter
+
+```typescript
+const result = await this.filter2Service.GetFilterData(
+  'LEAD',
+  [
+    {
+      filter_attribute: 'name',
+      filter_operator: 'contains',
+      filter_value: 'John',
+      filter_entity_type: 'LEAD',
+    },
+  ],
+  [],
+  [],
+  [],
+  undefined,
+  userData,
+  true, // flatJson
+  'entity_json',
+);
+
+// Generated SQL:
+// WHERE LOWER(e.entity_json->>'name') LIKE '%john%'
+```
+
+### Example 2: Number Filter
+
+```typescript
+const result = await this.filter2Service.GetFilterData(
+  'LEAD',
+  [
+    {
+      filter_attribute: 'salary',
+      filter_operator: 'greater_than',
+      filter_value: 50000,
+      filter_entity_type: 'LEAD',
+    },
+  ],
+  [],
+  [],
+  [],
+  undefined,
+  userData,
+  true,
+  'entity_json',
+);
+
+// Generated SQL:
+// WHERE (e.entity_json->>'salary')::numeric > 50000
+```
+
+### Example 3: Date Filter
+
+```typescript
+const result = await this.filter2Service.GetFilterData(
+  'LEAD',
+  [
+    {
+      filter_attribute: 'created_date',
+      filter_operator: 'after',
+      filter_value: '2024-01-01',
+      filter_entity_type: 'LEAD',
+    },
+  ],
+  [],
+  [],
+  [],
+  undefined,
+  userData,
+  true,
+  'entity_json',
+);
+
+// Generated SQL (dates stored as millisecond timestamps):
+// WHERE DATE(to_timestamp((e.entity_json->>'created_date')::bigint / 1000.0)) > '2024-01-01'
+```
+
+### Example 4: Multiple Filters
+
+```typescript
+const result = await this.filter2Service.GetFilterData(
+  'LEAD',
+  [
+    {
+      filter_attribute: 'name',
+      filter_operator: 'contains',
+      filter_value: 'John',
+      filter_entity_type: 'LEAD',
+    },
+    {
+      filter_attribute: 'status',
+      filter_operator: 'equal',
+      filter_value: 'ACTIVE',
+      filter_entity_type: 'LEAD',
+    },
+    {
+      filter_attribute: 'salary',
+      filter_operator: 'greater_than',
+      filter_value: 50000,
+      filter_entity_type: 'LEAD',
+    },
+  ],
+  [],
+  [],
+  [],
+  undefined,
+  userData,
+  true,
+  'entity_json',
+);
+
+// Generated SQL:
+// WHERE e.entity_type = 'LEAD'
+//   AND LOWER(e.entity_json->>'name') LIKE '%john%'
+//   AND e.entity_json->>'status' = 'ACTIVE'
+//   AND (e.entity_json->>'salary')::numeric > 50000
+```
+
+### Example 5: With Pagination and Sorting
+
+```typescript
+const result = await this.filter2Service.GetFilterData(
+  'LEAD',
+  [
+    {
+      filter_attribute: 'status',
+      filter_operator: 'equal',
+      filter_value: 'ACTIVE',
+      filter_entity_type: 'LEAD',
+    },
+  ],
+  [
+    { column: 'name', order: 'ASC' },
+    { column: 'created_date', order: 'DESC' },
+  ],
+  ['id', 'name', 'email', 'status', 'created_date'],
+  [],
+  { page: 2, size: 25 },
+  userData,
+  true,
+  'entity_json',
+);
+
+// Generated SQL:
+// SELECT
+//   e.entity_id AS id,
+//   e.entity_json->>'name' AS name,
+//   e.entity_json->>'email' AS email,
+//   e.entity_json->>'status' AS status,
+//   e.entity_json->>'created_date' AS created_date
+// FROM rez.entity_json AS e
+// WHERE e.entity_type = 'LEAD'
+//   AND e.entity_json->>'status' = 'ACTIVE'
+// ORDER BY e.entity_json->>'name' ASC, e.entity_json->>'created_date' DESC
+// LIMIT 25 OFFSET 25
+```
+
+### Example 6: Filter by IDs
+
+```typescript
+const result = await this.filter2Service.GetFilterData(
+  'LEAD',
+  [],
+  [],
+  [],
+  [101, 102, 103, 104, 105], // Specific entity IDs
+  undefined,
+  userData,
+  true,
+  'entity_json',
+);
+
+// Generated SQL:
+// WHERE e.entity_type = 'LEAD'
+//   AND e.entity_id::text = ANY('{101,102,103,104,105}')
+```
+
+### Example 7: Using GetFilterDataInternal
+
+```typescript
+const result = await this.filter2Service.GetFilterDataInternal(
+  'LEAD',
+  'MY_SAVED_FILTER', // Saved filter code
+  [
+    {
+      filter_attribute: 'status',
+      filter_operator: 'equal',
+      filter_value: 'ACTIVE',
+      filter_entity_type: 'LEAD',
+    },
+  ],
+  ['id', 'name', 'email'],
+  [],
+  userData,
+  true, // flatJson
+  'entity_json',
+);
+```
+
+### Example 8: Using GetFilterDataForListing
+
+```typescript
+const result = await this.filter2Service.GetFilterDataForListing(
+  'LEAD',
+  [
+    {
+      filter_attribute: 'name',
+      filter_operator: 'contains',
+      filter_value: 'Test',
+      filter_entity_type: 'LEAD',
+    },
+  ],
+  undefined, // No saved filter
+  [],
+  { column: 'name', order: 'ASC' },
+  { page: 1, size: 20 },
+  userData,
+  true, // flatJson
+  'entity_json',
+);
+
+// Automatically:
+// 1. Fetches layout preferences
+// 2. Uses columns from layout
+// 3. Uses sorting from layout
+// 4. Queries entity_json table
+```
+
+### Example 9: Multiselect Filter (Array Values)
+
+```typescript
+// Sample data in entity_json:
+// {
+//   "tags": ["important", "urgent", "follow-up"],
+//   "categories": ["sales", "marketing"]
+// }
+
+// Filter leads that have "important" tag
+const result = await this.filter2Service.GetFilterData(
+  'LEAD',
+  [
+    {
+      filter_attribute: 'tags',
+      filter_operator: 'contains', // or 'equal'
+      filter_value: 'important',
+      filter_entity_type: 'LEAD',
+    },
+  ],
+  [],
+  [],
+  [],
+  { page: 1, size: 20 },
+  userData,
+  true,
+  'entity_json',
+);
+
+// Generated SQL:
+// WHERE (e.entity_json->>'tags')::jsonb @> '["important"]'::jsonb
+
+// Filter leads that have ANY of these tags
+const resultAny = await this.filter2Service.GetFilterData(
+  'LEAD',
+  [
+    {
+      filter_attribute: 'tags',
+      filter_operator: 'contains_any',
+      filter_value: ['important', 'urgent'], // or 'important,urgent'
+      filter_entity_type: 'LEAD',
+    },
+  ],
+  [],
+  [],
+  [],
+  { page: 1, size: 20 },
+  userData,
+  true,
+  'entity_json',
+);
+
+// Generated SQL:
+// WHERE (e.entity_json->>'tags')::jsonb ?| ARRAY['important', 'urgent']
+
+// Filter leads that have ALL of these tags
+const resultAll = await this.filter2Service.GetFilterData(
+  'LEAD',
+  [
+    {
+      filter_attribute: 'tags',
+      filter_operator: 'contains_all',
+      filter_value: ['important', 'urgent'],
+      filter_entity_type: 'LEAD',
+    },
+  ],
+  [],
+  [],
+  [],
+  { page: 1, size: 20 },
+  userData,
+  true,
+  'entity_json',
+);
+
+// Generated SQL:
+// WHERE (e.entity_json->>'tags')::jsonb ?& ARRAY['important', 'urgent']
+```
+
+### Example 10: Date Filter (Millisecond Timestamps)
+
+```typescript
+// Sample data in entity_json:
+// {
+//   "created_date": 1704067200000,  // Jan 1, 2024 00:00:00 in milliseconds
+//   "modified_date": 1706745600000  // Feb 1, 2024 00:00:00 in milliseconds
+// }
+
+// Filter leads created after Jan 1, 2024
+const result = await this.filter2Service.GetFilterData(
+  'LEAD',
+  [
+    {
+      filter_attribute: 'created_date',
+      filter_operator: 'after',
+      filter_value: '2024-01-01',
+      filter_entity_type: 'LEAD',
+    },
+  ],
+  [],
+  [],
+  [],
+  { page: 1, size: 20 },
+  userData,
+  true,
+  'entity_json',
+);
+
+// Generated SQL (automatically converts milliseconds to timestamp):
+// WHERE DATE(to_timestamp((e.entity_json->>'created_date')::bigint / 1000.0)) > '2024-01-01'
+
+// Filter leads created between two dates
+const resultBetween = await this.filter2Service.GetFilterData(
+  'LEAD',
+  [
+    {
+      filter_attribute: 'created_date',
+      filter_operator: 'between',
+      filter_value: '2024-01-01,2024-12-31', // or ['2024-01-01', '2024-12-31']
+      filter_entity_type: 'LEAD',
+    },
+  ],
+  [],
+  [],
+  [],
+  { page: 1, size: 20 },
+  userData,
+  true,
+  'entity_json',
+);
+
+// Generated SQL:
+// WHERE DATE(to_timestamp((e.entity_json->>'created_date')::bigint / 1000.0))
+//       BETWEEN '2024-01-01' AND '2024-12-31'
+```
+
+### Example 11: Complex Filter (Mixed Data Types)
+
+```typescript
+// Sample data in entity_json:
+// {
+//   "name": "John Doe",
+//   "email": "john@example.com",
+//   "salary": 75000,
+//   "tags": ["important", "vip"],
+//   "created_date": 1704067200000,
+//   "status": ["ACTIVE"]
+// }
+
+const result = await this.filter2Service.GetFilterData(
+  'LEAD',
+  [
+    {
+      filter_attribute: 'name',
+      filter_operator: 'contains',
+      filter_value: 'John',
+      filter_entity_type: 'LEAD',
+    },
+    {
+      filter_attribute: 'salary',
+      filter_operator: 'greater_than',
+      filter_value: 50000,
+      filter_entity_type: 'LEAD',
+    },
+    {
+      filter_attribute: 'tags',
+      filter_operator: 'contains',
+      filter_value: 'vip',
+      filter_entity_type: 'LEAD',
+    },
+    {
+      filter_attribute: 'created_date',
+      filter_operator: 'after',
+      filter_value: '2024-01-01',
+      filter_entity_type: 'LEAD',
+    },
+    {
+      filter_attribute: 'status',
+      filter_operator: 'equal',
+      filter_value: 'ACTIVE',
+      filter_entity_type: 'LEAD',
+    },
+  ],
+  [{ column: 'created_date', order: 'DESC' }],
+  ['id', 'name', 'email', 'salary', 'tags', 'status'],
+  [],
+  { page: 1, size: 20 },
+  userData,
+  true,
+  'entity_json',
+);
+
+// Generated SQL:
+// SELECT
+//   e.entity_id AS id,
+//   e.entity_json->>'name' AS name,
+//   e.entity_json->>'email' AS email,
+//   e.entity_json->>'salary' AS salary,
+//   e.entity_json->>'tags' AS tags,
+//   e.entity_json->>'status' AS status
+// FROM rez.entity_json AS e
+// WHERE e.entity_type = 'LEAD'
+//   AND LOWER(e.entity_json->>'name') LIKE '%john%'
+//   AND (e.entity_json->>'salary')::numeric > 50000
+//   AND (e.entity_json->>'tags')::jsonb @> '["vip"]'::jsonb
+//   AND DATE(to_timestamp((e.entity_json->>'created_date')::bigint / 1000.0)) > '2024-01-01'
+//   AND (e.entity_json->>'status')::jsonb @> '["ACTIVE"]'::jsonb
+// ORDER BY to_timestamp((e.entity_json->>'created_date')::bigint / 1000.0) DESC
+// LIMIT 20 OFFSET 0
+```
+
+## Supported Operators
+
+### Text Operators
+- `contains` - Case-insensitive partial match
+- `equal` - Exact match
+- `not_equal` - Not equal
+- `empty` - IS NULL or empty string
+- `not_empty` - IS NOT NULL and not empty string
+
+**SQL Examples:**
+```sql
+-- contains
+LOWER(e.entity_json->>'name') LIKE '%john%'
+
+-- equal
+e.entity_json->>'name' = 'John Doe'
+
+-- empty
+(e.entity_json->>'name' IS NULL OR e.entity_json->>'name' = '')
+```
+
+### Number Operators
+- `equal`
+- `not_equal`
+- `greater_than`
+- `less_than`
+- `greater_than_qual_to`
+- `less_than_qual_to`
+- `empty`
+- `not_empty`
+
+**SQL Examples:**
+```sql
+-- greater_than
+(e.entity_json->>'salary')::numeric > 50000
+
+-- less_than_qual_to
+(e.entity_json->>'age')::numeric <= 30
+```
+
+### Date Operators
+- `equal` / `is`
+- `before` / `is_before`
+- `after` / `is_after`
+- `is_on_or_before`
+- `is_on_or_after`
+- `between`
+- `empty`
+- `not_empty`
+
+**Note:** Dates are stored as timestamp milliseconds in flatjson.
+
+**SQL Examples:**
+```sql
+-- after (with millisecond timestamp conversion)
+DATE(to_timestamp((e.entity_json->>'created_date')::bigint / 1000.0)) > '2024-01-01'
+
+-- between (with millisecond timestamp conversion)
+DATE(to_timestamp((e.entity_json->>'created_date')::bigint / 1000.0)) BETWEEN '2024-01-01' AND '2024-12-31'
+
+-- Millisecond timestamp conversion:
+-- to_timestamp(milliseconds::bigint / 1000.0) converts ms to timestamp
+```
+
+### Select/Multiselect Operators
+- `equal` / `contains` - Check if array contains a specific value
+- `not_equal` / `not_contains` - Check if array does NOT contain a specific value
+- `contains_any` - Check if array contains ANY of the provided values
+- `contains_all` - Check if array contains ALL of the provided values
+- `empty` - Check if null, empty string, or empty array
+- `not_empty` - Check if not null and not empty array
+
+**Note:** Multiselect values are stored as JSON arrays: `["value1", "value2"]`
+
+**SQL Examples:**
+```sql
+-- equal/contains (single value in array)
+(e.entity_json->>'status')::jsonb @> '["ACTIVE"]'::jsonb
+
+-- not_equal/not_contains
+NOT ((e.entity_json->>'status')::jsonb @> '["ACTIVE"]'::jsonb)
+
+-- contains_any (using ?| operator)
+(e.entity_json->>'tags')::jsonb ?| ARRAY['important', 'urgent']
+
+-- contains_all (using ?& operator)
+(e.entity_json->>'tags')::jsonb ?& ARRAY['important', 'urgent']
+
+-- empty (null, empty string, or empty array)
+(e.entity_json->>'tags' IS NULL OR e.entity_json->>'tags' = '' OR jsonb_array_length((e.entity_json->>'tags')::jsonb) = 0)
+
+-- PostgreSQL JSONB Operators used:
+-- @> : containment operator (left contains right)
+-- ?| : does the array contain any of these keys/values
+-- ?& : does the array contain all of these keys/values
+```
+
+## Comparison: Regular vs FlatJson
+
+### Data Storage
+
+| Aspect | Regular Entity | FlatJson Entity |
+|--------|----------------|-----------------|
+| Table | Dedicated (e.g., `frm_lead`) | `entity_json` |
+| Schema | Fixed columns | Flexible JSON |
+| Attributes | Table columns | JSON properties |
+| Storage Type | DB_COL or EAV | JSON |
+| Flexibility | Low (schema change needed) | High (no schema change) |
+
+### Query Performance
+
+| Operation | Regular | FlatJson |
+|-----------|---------|----------|
+| Simple filter | Fast | Fast |
+| Multiple filters | Fast | Moderate |
+| Sorting | Fast (indexed) | Moderate (JSON ops) |
+| Pagination | Fast | Fast |
+| Full-text search | Fast (with indexes) | Slower |
+
+### When to Use FlatJson
+
+✅ **Use FlatJson when:**
+- Schema changes frequently
+- Attributes are dynamic per entity
+- Rapid prototyping needed
+- Data structure varies by tenant
+- Flexible data model required
+
+❌ **Avoid FlatJson when:**
+- High-performance queries needed
+- Complex joins required
+- Large datasets (millions of rows)
+- Frequent aggregations
+- Need database-level constraints
+
+## PostgreSQL JSON Operators
+
+The FlatJson implementation uses PostgreSQL JSON operators:
+
+| Operator | Description | Example |
+|----------|-------------|---------|
+| `->` | Get JSON object field | `entity_json->'name'` |
+| `->>` | Get JSON object field as text | `entity_json->>'name'` |
+| `::numeric` | Cast to numeric | `(entity_json->>'salary')::numeric` |
+| `::jsonb` | Cast to JSONB | `(entity_json->>'tags')::jsonb` |
+| `::bigint` | Cast to bigint | `(entity_json->>'created_date')::bigint` |
+| `to_timestamp()` | Convert milliseconds to timestamp | `to_timestamp(ms::bigint / 1000.0)` |
+| `DATE()` | Extract date | `DATE(to_timestamp(ms::bigint / 1000.0))` |
+| `@>` | JSONB containment operator | `'["a","b"]'::jsonb @> '["a"]'::jsonb` |
+| `?|` | JSONB contains ANY operator | `'["a","b"]'::jsonb ?| ARRAY['a','c']` |
+| `?&` | JSONB contains ALL operator | `'["a","b"]'::jsonb ?& ARRAY['a','b']` |
+| `jsonb_array_length()` | Get JSONB array length | `jsonb_array_length('["a","b"]'::jsonb)` |
+
+## Data Format Considerations
+
+### Date/Time Storage
+
+**Important:** Dates and times in FlatJson are stored as **timestamp milliseconds** (not regular timestamps).
+
+**Example Data:**
+```json
+{
+  "entity_json": {
+    "created_date": 1704067200000,  // Jan 1, 2024 00:00:00 in milliseconds
+    "modified_date": 1706745600000
+  }
+}
+```
+
+**Filter Implementation:**
+The service automatically converts millisecond timestamps to proper timestamps:
+```sql
+-- Conversion formula:
+to_timestamp((e.entity_json->>'created_date')::bigint / 1000.0)
+
+-- Usage in filter:
+DATE(to_timestamp((e.entity_json->>'created_date')::bigint / 1000.0)) > '2024-01-01'
+```
+
+### Multiselect Storage
+
+**Important:** Multiselect values in FlatJson are stored as **JSON arrays**, not strings.
+
+**Example Data:**
+```json
+{
+  "entity_json": {
+    "tags": ["important", "urgent", "follow-up"],
+    "status": ["ACTIVE"],
+    "categories": []
+  }
+}
+```
+
+**Filter Implementation:**
+The service uses PostgreSQL JSONB operators for array operations:
+```sql
+-- Check if array contains a value:
+(e.entity_json->>'tags')::jsonb @> '["important"]'::jsonb
+
+-- Check if array contains ANY values:
+(e.entity_json->>'tags')::jsonb ?| ARRAY['important', 'urgent']
+
+-- Check if array contains ALL values:
+(e.entity_json->>'tags')::jsonb ?& ARRAY['important', 'urgent']
+
+-- Check if array is empty:
+jsonb_array_length((e.entity_json->>'tags')::jsonb) = 0
+```
+
+### Single-Select Storage
+
+Single-select values can be stored as either strings or single-element arrays:
+```json
+{
+  "entity_json": {
+    "status": ["ACTIVE"],  // Array format (recommended for consistency)
+    "type": "LEAD"         // String format (also supported)
+  }
+}
+```
+
+**Best Practice:** Store all select fields as arrays for consistency, even single-select fields.
+
+## Performance Optimization
+
+### 1. Create GIN Index on JSON Column
+
+```sql
+CREATE INDEX idx_entity_json_gin
+ON entity_json USING GIN (entity_json);
+```
+
+### 2. Create Expression Index for Common Filters
+
+```sql
+-- Index for name searches
+CREATE INDEX idx_entity_json_name
+ON entity_json ((entity_json->>'name'));
+
+-- Index for status filters
+CREATE INDEX idx_entity_json_status
+ON entity_json ((entity_json->>'status'));
+
+-- Index for date filters
+CREATE INDEX idx_entity_json_created_date
+ON entity_json (((entity_json->>'created_date')::timestamp));
+```
+
+### 3. Partition by Entity Type
+
+```sql
+CREATE TABLE entity_json_lead PARTITION OF entity_json
+FOR VALUES IN ('LEAD');
+
+CREATE TABLE entity_json_contact PARTITION OF entity_json
+FOR VALUES IN ('CONTACT');
+```
+
+### 4. Use Specific Column Selection
+
+```typescript
+// ❌ Bad: Returns entire JSON
+const bad = await filter2Service.GetFilterData(
+  'LEAD', [], [], [], [], undefined, userData, true, 'entity_json'
+);
+
+// ✅ Good: Returns only needed columns
+const good = await filter2Service.GetFilterData(
+  'LEAD', [], [], ['id', 'name', 'email'], [], undefined, userData, true, 'entity_json'
+);
+```
+
+## Migration from Regular to FlatJson
+
+### Step 1: Copy Data to entity_json
+
+```sql
+INSERT INTO entity_json (entity_type, entity_id, entity_json, created_date, modified_date)
+SELECT
+  'LEAD' AS entity_type,
+  id AS entity_id,
+  jsonb_build_object(
+    'name', name,
+    'email', email,
+    'phone', phone,
+    'status', status,
+    'salary', salary
+  ) AS entity_json,
+  created_date,
+  modified_date
+FROM frm_lead;
+```
+
+### Step 2: Update Application Code
+
+```typescript
+// Old way (regular table)
+const oldResult = await filter2Service.GetFilterData(
+  'LEAD',
+  filters,
+  sortColumns,
+  columns,
+  [],
+  pagination,
+  userData,
+  false, // flatJson = false
+);
+
+// New way (flatjson)
+const newResult = await filter2Service.GetFilterData(
+  'LEAD',
+  filters,
+  sortColumns,
+  columns,
+  [],
+  pagination,
+  userData,
+  true, // flatJson = true
+  'entity_json',
+);
+```
+
+### Step 3: Verify Data
+
+```typescript
+// Test query
+const test = await filter2Service.GetFilterData(
+  'LEAD',
+  [],
+  [],
+  ['id', 'name', 'email'],
+  [1, 2, 3], // Test with specific IDs
+  undefined,
+  userData,
+  true,
+  'entity_json',
+);
+
+console.log(test.entity_list);
+```
+
+## Error Handling
+
+### Invalid JSON Path
+
+```typescript
+try {
+  const result = await filter2Service.GetFilterData(
+    'LEAD',
+    [
+      {
+        filter_attribute: 'nonexistent_field',
+        filter_operator: 'equal',
+        filter_value: 'test',
+        filter_entity_type: 'LEAD',
+      },
+    ],
+    [],
+    [],
+    [],
+    undefined,
+    userData,
+    true,
+    'entity_json',
+  );
+} catch (error) {
+  // Handle gracefully - will return NULL for non-existent fields
+  console.log('Field not found in JSON');
+}
+```
+
+### Type Casting Errors
+
+```typescript
+// Attempting to cast non-numeric value to numeric
+try {
+  const result = await filter2Service.GetFilterData(
+    'LEAD',
+    [
+      {
+        filter_attribute: 'name', // Text field
+        filter_operator: 'greater_than', // Numeric operator
+        filter_value: 100,
+        filter_entity_type: 'LEAD',
+      },
+    ],
+    [],
+    [],
+    [],
+    undefined,
+    userData,
+    true,
+    'entity_json',
+  );
+} catch (error) {
+  console.error('Type casting error:', error.message);
+  // "invalid input syntax for type numeric"
+}
+```
+
+## Summary
+
+FlatJson support in Filter2Service provides:
+
+✅ **Flexible Schema** - No database migrations needed for new attributes
+✅ **Full Filter Support** - All operators work on JSON fields
+✅ **PostgreSQL JSON Operators** - Leverages native JSON capabilities
+✅ **Pagination & Sorting** - Works just like regular queries
+✅ **Layout Preferences** - Integrates with existing UI preferences
+✅ **Performance** - Optimized with GIN indexes and expression indexes
+
+Use flatJson when you need schema flexibility. Use regular tables when you need maximum performance.