@linkup-ai/abap-ai 2.0.0

package/dist/knowledge/abap-cds/expressions.md

@@ -0,0 +1,230 @@
+# CDS Expressions — Operators, CASE, Aggregates, Types
+
+## Field References
+
+```sql
+{
+  key matnr,                          -- simple
+  key source.matnr,                   -- with alias prefix
+  matnr as MaterialNumber,            -- with alias
+  'EUR' as DefaultCurrency,           -- char literal (alias required)
+  100 as DefaultQty,                  -- integer literal
+  abap.dats'20241115' as FixedDate    -- typed literal
+}
+```
+
+## Session Variables
+
+```sql
+{
+  $session.user as CurrentUser,             -- SY-UNAME
+  $session.client as ClientId,              -- SY-MANDT
+  $session.system_language as Language,      -- SY-LANGU
+  $session.system_date as Today             -- SY-DATUM (7.51+)
+}
+```
+
+## Comparison Operators
+
+| Operator | Example |
+|----------|---------|
+| `=` | `status = 'A'` |
+| `<>` | `status <> 'D'` |
+| `<` `>` `<=` `>=` | `amount > 0` |
+| `between ... and ...` | `date between '20240101' and '20241231'` |
+| `in (...)` | `status in ('A','B','C')` |
+| `is null` / `is not null` | `description is not null` |
+| `like` | `name like 'SAP%'` |
+
+### LIKE Patterns
+
+```sql
+where name like 'SAP%'           -- starts with
+where name like '%GmbH'          -- ends with
+where name like '%Partner%'      -- contains
+where code like 'A_B'            -- single char wildcard
+where name like '%10#%%' escape '#'  -- literal % via escape
+```
+
+## Arithmetic
+
+```sql
+{
+  quantity * unit_price as LineTotal,
+  gross_amount - discount as NetAmount,
+  total / 100 as Percentage,
+  -balance as NegatedBalance,
+  (10 + 5) * 2 as WithParens        -- = 30, not 20
+}
+```
+
+Precedence: `()` > `-`(unary) > `*` `/` > `+` `-`
+
+## CASE — Simple
+
+```sql
+case status
+  when 'A' then 'Active'
+  when 'I' then 'Inactive'
+  when 'D' then 'Deleted'
+  else 'Unknown'
+end as StatusText
+```
+
+## CASE — Searched
+
+```sql
+case
+  when amount > 10000 then 'High'
+  when amount > 1000  then 'Medium'
+  when amount > 0     then 'Low'
+  else 'Zero'
+end as AmountCategory
+```
+
+## CASE — Nested
+
+```sql
+case type
+  when 'S' then
+    case status
+      when 'A' then 'Sales Active'
+      when 'C' then 'Sales Closed'
+      else 'Sales Other'
+    end
+  when 'P' then 'Purchase'
+  else 'Other'
+end as TypeDescription
+```
+
+## CASE — With Calculation
+
+```sql
+case indicator
+  when 'H' then amount
+  when 'S' then -amount
+  else 0
+end as SignedAmount
+```
+
+## Logical Operators
+
+```sql
+-- AND / OR / NOT
+where status = 'A' and type = 'S'
+where status = 'A' or status = 'B'
+where not status = 'D'
+
+-- Precedence: NOT > AND > OR — use parentheses
+where (status = 'A' and type = 'S')
+   or (status = 'B' and priority > 5)
+```
+
+## Aggregate Functions
+
+| Function | Usage |
+|----------|-------|
+| `sum(field)` | Sum |
+| `avg(field)` | Average |
+| `min(field)` | Minimum |
+| `max(field)` | Maximum |
+| `count(*)` | Row count |
+| `count(distinct field)` | Distinct count |
+
+## GROUP BY / HAVING
+
+```sql
+define view Z_CUST_SUMMARY as select from zvbak
+{
+  kunnr,
+  sum(netwr) as TotalSales,
+  avg(netwr) as AvgOrder,
+  min(erdat) as FirstOrder,
+  max(erdat) as LastOrder,
+  count(*) as OrderCount,
+  count(distinct matnr) as UniqueProducts
+}
+group by kunnr
+having count(*) >= 5
+```
+
+## Path Expressions
+
+```sql
+-- Single level
+_Customer.name1 as CustomerName
+
+-- Multi-level
+_Order._Customer._Country.name as CountryName
+
+-- Path with filter + cardinality indicator
+_Items[1: ItemNumber = '000010'].Material as FirstMaterial
+```
+
+## Conditional Navigation
+
+```sql
+case
+  when type = 'C' then _Customer.name1
+  when type = 'V' then _Vendor.name1
+  else 'Unknown'
+end as PartnerName
+```
+
+## NULL Handling
+
+```sql
+-- COALESCE: first non-null
+coalesce(override_price, standard_price, 0) as EffectivePrice
+
+-- Arithmetic with NULL returns NULL
+price - discount as NetPrice              -- NULL if discount NULL
+price - coalesce(discount, 0) as NetPrice -- safe
+```
+
+## CAST
+
+```sql
+cast(numc_field as abap.char(10)) as TextField,
+cast(char_field as abap.int4) as IntField,
+cast(amount as abap.curr(15,2)) as FormattedAmount,
+cast('EUR' as abap.cuky) as Currency
+```
+
+### Common ABAP Types for CAST
+
+| Type | Syntax |
+|------|--------|
+| Character | `abap.char(n)` |
+| Numeric text | `abap.numc(n)` |
+| Integer | `abap.int4` |
+| Date | `abap.dats` |
+| Time | `abap.tims` |
+| Currency key | `abap.cuky` |
+| Currency amount | `abap.curr(n,d)` |
+| Unit | `abap.unit(n)` |
+| Quantity | `abap.quan(n,d)` |
+| Decimal | `abap.dec(n,d)` |
+| String | `abap.string` |
+
+## Rules
+
+- Literals always require an alias
+- All CASE branches must return the same type
+- Always use COALESCE or CASE for NULL-prone calculations
+- Always alias calculated/expression fields
+- Use parentheses in complex WHERE to clarify precedence
+- GROUP BY must list all non-aggregated fields
+- `$session.system_date` requires NW 7.51+
+
+## Anti-Patterns
+
+| Anti-Pattern | Correct |
+|---|---|
+| Arithmetic on nullable field without COALESCE | `coalesce(field, 0)` before math |
+| CASE branches returning mixed types | Ensure all branches return same type |
+| Missing GROUP BY field | List every non-aggregated field |
+| `where a = 1 or b = 2 and c = 3` without parens | `where a = 1 or (b = 2 and c = 3)` |
+| Unaliased expression in projection | Always alias: `expr as AliasName` |
+| CASE in WHERE on large datasets | Use separate WHERE conditions for performance |
+| Using `$session.system_date` on NW < 7.51 | Use parameter with `@Environment.systemField` |

package/dist/knowledge/abap-cds/functions.md

@@ -0,0 +1,245 @@
+# CDS Built-in Functions — String, Numeric, Date, Conversion
+
+## String Functions
+
+```sql
+-- concat / concat_with_space
+concat(first_name, last_name) as Full               -- 'JohnDoe'
+concat_with_space(first_name, last_name, 1) as Full  -- 'John Doe'
+
+-- length
+length(description) as Len                           -- 5
+
+-- left / right / substring (1-based)
+left(matnr, 4) as Prefix                            -- '1234'
+right(matnr, 3) as Suffix                           -- '678'
+substring(docnum, 3, 5) as Sub                       -- '34567'
+
+-- upper / lower
+upper(name) as Up                                    -- 'HELLO'
+lower(name) as Lo                                    -- 'hello'
+
+-- lpad / rpad
+lpad(docnum, 10, '0') as Padded                      -- '0000012345'
+rpad(name, 20, ' ') as PaddedR                       -- 'John                '
+
+-- ltrim / rtrim
+ltrim(docnum, '0') as Trimmed                        -- '12345'
+rtrim(name, ' ') as TrimmedR                         -- 'John'
+
+-- replace
+replace(phone, '-', '') as Clean                     -- '1234567890'
+
+-- instr (0 if not found)
+instr(email, '@') as AtPos                           -- 5
+```
+
+## Numeric Functions
+
+```sql
+-- abs
+abs(-100) as Val                                     -- 100
+
+-- ceil / floor
+ceil(5.1) as Up                                      -- 6
+floor(5.9) as Down                                   -- 5
+
+-- round
+round(5.567, 2) as R                                 -- 5.57
+round(12345, -2) as R2                               -- 12300
+
+-- div / mod (integer)
+div(125, 60) as Hours                                -- 2
+mod(125, 60) as Mins                                 -- 5
+
+-- division (with decimal precision)
+division(10, 3, 4) as R                              -- 3.3333
+```
+
+## Date Functions
+
+```sql
+-- dats_add_days
+dats_add_days(order_date, 7) as Delivery             -- +7 days
+dats_add_days(order_date, -30) as PrevMonth           -- -30 days
+
+-- dats_add_months
+dats_add_months(start_date, 1) as NextMonth          -- +1 month
+
+-- dats_days_between (negative if date1 > date2)
+dats_days_between(order_date, delivery_date) as Lead -- 14
+
+-- dats_is_valid (returns 1 or 0)
+dats_is_valid(input_date) as IsValid                 -- 1 or 0
+```
+
+## Timestamp Functions
+
+```sql
+-- Add seconds
+tstmp_add_seconds(created_at, 3600, 'FAIL') as PlusHour
+
+-- Seconds between
+tstmp_seconds_between(start_ts, end_ts, 'FAIL') as Duration
+
+-- Current UTC
+tstmp_current_utctimestamp() as Now
+```
+
+Third param: `'FAIL'` to raise error, `'NULL'` to return null on invalid input.
+
+## COALESCE
+
+```sql
+coalesce(override_price, standard_price, 0) as Price
+coalesce(customer_name, 'Unknown') as Name
+```
+
+## CAST
+
+```sql
+cast(numc_field as abap.char(10)) as Text,
+cast(char_field as abap.int4) as Int,
+cast(amount as abap.curr(15,2)) as Amt,
+cast('EUR' as abap.cuky) as Cur,
+cast(num as abap.dec(11,2)) as Dec
+```
+
+### Types
+
+| Type | Syntax |
+|------|--------|
+| `abap.char(n)` | Character |
+| `abap.numc(n)` | Numeric text |
+| `abap.int4` | Integer |
+| `abap.dats` | Date |
+| `abap.tims` | Time |
+| `abap.cuky` | Currency key |
+| `abap.curr(n,d)` | Currency amount |
+| `abap.unit(n)` | Unit of measure |
+| `abap.quan(n,d)` | Quantity |
+| `abap.dec(n,d)` | Decimal |
+| `abap.string` | String |
+
+## Aggregate Functions
+
+```sql
+define view Z_ORDER_AGG as select from vbap
+{
+  vbeln,
+  sum(netwr) as Total,
+  count(*) as Items,
+  min(erdat) as FirstDate,
+  max(erdat) as LastDate,
+  avg(netwr) as AvgAmt,
+  count(distinct matnr) as UniqueMatnr
+}
+group by vbeln
+having sum(netwr) > 1000
+```
+
+## Conversion Functions
+
+```sql
+-- Decimal shift by currency
+decimal_shift(amount => netwr, currency => waers) as Shifted
+
+-- Unit conversion (HANA, requires T006)
+unit_conversion(
+  quantity      => menge,
+  source_unit   => meins,
+  target_unit   => 'KG'
+) as QtyKG
+
+-- Currency conversion (HANA, requires TCURR)
+currency_conversion(
+  amount             => netwr,
+  source_currency    => waers,
+  target_currency    => 'EUR',
+  exchange_rate_date => erdat
+) as AmtEUR
+```
+
+## Complex Examples
+
+### Minutes to HH:MM
+
+```sql
+concat(
+  concat(
+    lpad(ltrim(cast(div(flight_time, 60) as abap.char(12)), '0'), 2, '0'),
+    ':'
+  ),
+  lpad(ltrim(cast(mod(flight_time, 60) as abap.char(12)), '0'), 2, '0')
+) as FormattedTime
+-- 125 => '02:05'
+```
+
+### Date Validation with Default
+
+```sql
+case
+  when dats_is_valid(input_date) = 1 then input_date
+  else '00000000'
+end as ValidatedDate
+```
+
+### Conditional Concatenation
+
+```sql
+case
+  when last_name is not null
+    then concat_with_space(first_name, last_name, 1)
+  else first_name
+end as DisplayName
+```
+
+### Safe Percentage
+
+```sql
+case
+  when total > 0
+    then division(part * 100, total, 2)
+  else cast(0 as abap.dec(5,2))
+end as Percentage
+```
+
+### Nested Functions
+
+```sql
+upper(
+  replace(
+    ltrim(
+      concat_with_space(first_name, last_name, 1),
+      ' '
+    ),
+    ' ',
+    '_'
+  )
+) as NormalizedName
+-- '  John Doe  ' => 'JOHN_DOE'
+```
+
+## Rules
+
+- `substring` position is 1-based, not 0-based
+- `lpad` truncates if original exceeds target length
+- `dats_days_between` returns negative if date1 > date2
+- `division` third param = decimal places; `div` returns integer
+- `unit_conversion` / `currency_conversion` require HANA + maintained tables
+- Always validate dates with `dats_is_valid` before date arithmetic
+- Use `coalesce` before arithmetic on nullable fields
+- Aggregate functions require GROUP BY for all non-aggregated fields
+
+## Anti-Patterns
+
+| Anti-Pattern | Correct |
+|---|---|
+| `concat(concat(a, ' '), b)` for space join | `concat_with_space(a, b, 1)` |
+| Date math without `dats_is_valid` check | Validate first, then calculate |
+| `division(a, b, 2)` without zero check | Wrap in `case when b > 0` |
+| `substring(f, 0, 5)` (0-based) | `substring(f, 1, 5)` — 1-based |
+| Nested 5+ function calls | Break into intermediate views |
+| `unit_conversion` on non-HANA DB | Check platform support first |
+| Missing GROUP BY with aggregates | List every non-aggregated field |
+| `ltrim(field, ' ')` expecting full trim | Only trims from left side |