catalyst-nosql

어떤 스킬인가요?

Catalyst NoSQL — key-value table store with typed items built via NoSQLItem builder. Partition key required. Trigger on 'NoSQL', 'nosql.table', 'insertItems', 'fetchItem', 'updateItems', 'deleteItems', 'queryTable', 'NoSQLItem', 'document storage', 'flexible schema', or 'Catalyst document database'. Do NOT use when you need SQL joins, ZCQL queries, or a fixed relational schema — use catalyst-datastore instead.

설치 방법

프로젝트 폴더에서 아래 명령어를 실행하고, 설치할 에이전트를 선택하세요.

설치 명령을 직접 실행해야 적용됩니다. 지원 에이전트와 필요한 권한·라이선스는 제작자의 안내를 확인하세요.

스킬 원문 파일

## Overview

Catalyst NoSQL is a key-value store organized into **tables**. Each table requires a
**partition key** (and optionally a sort key) defined at creation time. Items are typed
attribute maps built with the `NoSQLItem` builder — not plain JSON objects.

> **Pre-requisite:** Create the table in the console (Console → Cloud Scale → NoSQL)
before writing SDK code. The table name and partition-key column name must be known.

## Data model

| Concept | Catalyst NoSQL |
|---------|----------------|
| Container | Table (not "collection") |
| Row | Item — typed attribute map |
| Primary key | Partition key (required) + optional sort key |
| Schema | Per-item flexible — any extra attributes allowed |
| Query | Partition-key equality condition (required) + optional filter |

## SDK Operations (Node.js)

```javascript
const { NoSQLItem, NoSQLMarshall, NoSQLEnum } = require('zcatalyst-sdk-node/lib/no-sql');
const { NoSQLOperator, NoSQLUpdateOperationType } = NoSQLEnum;

const nosql = catalystApp.nosql();
// nosql.table(name) returns an instance without an API call
const table = nosql.table('UserProfiles');
// Table name from Console → Cloud Scale → NoSQL

// --- INSERT ---
// insertItems(...items) — spread one or more INoSQLInsertItem objects
await table.insertItems({
  item: new NoSQLItem()
    .addString('userId', 'u123')        // partition key
    .addString('name', 'Alice')
    .addNumber('age', 30)
    .addBoolean('active', true)
});

// --- FETCH by key ---
// fetchItem({ keys }) — keys can be a single NoSQLItem or an array for batch fetch
const result = await table.fetchItem({
  keys: new NoSQLItem().addString('userId', 'u123')
});
// result.toJSON() → INoSQLResponse with result.create/get/update/delete arrays

// --- UPDATE ---
// updateItems(...updates) — keys identifies the item; update_attributes describes what to change
await table.updateItems({
  keys: new NoSQLItem().addString('userId', 'u123'),
  update_attributes: [
    {
      operation_type: NoSQLUpdateOperationType.PUT,
      attribute_path: ['name'],
      update_value: NoSQLMarshall.makeString('Alice Smith')
    }
  ]
});

// --- DELETE ---
// deleteItems(...deletes) — keys must include the partition key (and sort key if table has one)
await table.deleteItems({
  keys: new NoSQLItem().addString('userId', 'u123')
});

// --- QUERY ---
// queryTable({ key_condition, limit? }) — must include partition-key equality as condition
const queryResult = await table.queryTable({
  key_condition: {
    attribute: ['userId'],
    operator: NoSQLOperator.EQUALS,
    value: NoSQLMarshall.makeString('u123')
  },
  limit: 50
});
```

## NoSQLItem builder cheat-sheet

| Method | DynamoDB type | Example |
|--------|--------------|----------|
| `.addString(name, val)` | S | `.addString('city', 'NYC')` |
| `.addNumber(name, val)` | N | `.addNumber('score', 42)` |
| `.addBoolean(name, val)` | BOOL | `.addBoolean('active', true)` |
| `.addNull(name)` | NULL | `.addNull('deletedAt')` |
| `.addList(name, arr)` | L | `.addList('tags', [NoSQLMarshall.makeString('beta')])` |
| `.addMap(name, obj)` | M | `.addMap('meta', { src: NoSQLMarshall.makeString('web') })` |
| `NoSQLItem.from(obj)` | auto-marshall | `NoSQLItem.from({ userId: 'u1' })` |

## When to Use NoSQL vs Data Store

| Use NoSQL | Use Data Store |
|-----------|---------------|
| Flexible / evolving per-item attributes | Fixed schema with uniform columns |
| Nested maps or arrays in items | Flat tabular data |
| No complex joins needed | Joins or ZCQL queries required |
| High write throughput, key-value access | ACID compliance, relational access |

## Common Errors

| Error | Cause | Fix |
|-------|-------|-----|
| `nosql.collection is not a function` | Using the old (wrong) API | Replace with `nosql.table(name)` — there is no `collection()` method |
| `table.insertDocument is not a function` | Using the old (wrong) API | Replace with `table.insertItems({ item: new NoSQLItem()... })` |
| Table not found / 404 | Table doesn't exist yet or name is wrong | Create via Console → NoSQL before running SDK code; names are case-sensitive |
| Insert returns 400 | Partition key attribute missing from `NoSQLItem` | Ensure the NoSQLItem includes the partition-key column defined in the Console |
| `queryTable` returns empty despite data existing | `key_condition.attribute` path wrong | Use the exact column name (case-sensitive) defined as the partition key in the Console |

---
name: catalyst-nosql
description: "Catalyst NoSQL — key-value table store with typed items built via NoSQLItem builder. Partition key required. Trigger on 'NoSQL', 'nosql.table', 'insertItems', 'fetchItem', 'updateItems', 'deleteItems', 'queryTable', 'NoSQLItem', 'document storage', 'flexible schema', or 'Catalyst document database'. Do NOT use when you need SQL joins, ZCQL queries, or a fixed relational schema — use catalyst-datastore instead."
metadata:
  version: "2.1.0"
---

## How It Works

1. **NoSQL vs Data Store** — If the user is undecided, apply this matrix:

   | | Catalyst Data Store | Catalyst NoSQL |
   |---|---|---|
   | Schema | Fixed, defined upfront | Flexible, per-item (no uniform structure required) |
   | Query | ZCQL (SQL-like joins and filters) | Partition key + optional sort key |
   | Data type | Structured, relational rows | Unstructured/semi-structured, JSON-format |
   | Priority | ACID compliance, complex queries | High scalability, high write throughput |

   **Rule:** If the user says "ZCQL", "join", "relational", or "fixed schema" — stop and load `catalyst-datastore` instead.
2. **Load `references/nosql-basics.md`** — for SDK operations (`insertItems`, `fetchItem`, `updateItems`, `deleteItems`, `queryTable`) and the `NoSQLItem` builder.
3. **Answer** — Provide the SDK method call with the correct table name, partition-key attribute, and `NoSQLItem` construction.

## Triggers

Use this skill for: "NoSQL", "document storage", `nosql.table`, `insertItems`, `fetchItem`, `updateItems`, `deleteItems`, `queryTable`, `NoSQLItem`, "NoSQL vs Data Store", "flexible schema", "Catalyst document database", "schemaless data on Catalyst", or "nested objects in Catalyst".

## References

| Reference | Load when the query is about… |
|-----------|-------------------------------|
| `references/nosql-basics.md` | SDK operations (`insertItems`, `fetchItem`, `updateItems`, `deleteItems`, `queryTable`), `NoSQLItem` builder, partition-key model, NoSQL vs Data Store decision table |