Bazy danych Noe

Tworzenie i konfiguracja elastycznych baz JSON oraz operacje na rekordach - przez API i przez publiczne metody (dla frontendów aplikacji Noe, bez autoryzacji).

Autoryzacja: Authorization: Bearer TOKEN (poza metodami publicznymi) Content-Type: application/json; charset=utf-8

API Endpoints

Metoda	Ścieżka	Opis
GET	/noe/dbs.json	Lista baz
GET	/noe/dbs/:id.json	Szczegóły bazy (:id = id lub code)
POST	/noe/dbs.json	Utworzenie bazy
PATCH	/noe/dbs/:id.json	Aktualizacja bazy
DELETE	/noe/dbs/:id.json	Usunięcie bazy (z rekordami!)
PATCH	/noe/dbs/:id/replace.json	Częściowa edycja pól fields/schema/public_methods
GET	/noe/dbs/:db_id/records.json	Lista rekordów
POST	/noe/dbs/:db_id/records.json	Utworzenie rekordu (z table_name dla baz wielotabelowych)
PATCH	/noe/dbs/:db_id/records/:id.json	Aktualizacja rekordu
DELETE	/noe/dbs/:db_id/records/:id.json	Usunięcie rekordu
GET	/noe/dbs/:db_id/search.json	Wyszukiwanie rekordów (table_name, q, search_in, filter[], fields, sort)
GET/POST	/noe/db/:db_code/:method_name	Metody publiczne (bez autoryzacji, wg public_methods)

Utworzenie bazy

POST /noe/dbs.json
{
  "db": {
    "name": "Todo",
    "code": "todo",
    "app_id": "uuid-aplikacji (opcjonalnie)",
    "schema": {
      "fields": {
        "title": { "type": "string", "required": true },
        "done": { "type": "integer" }
      },
      "indexes": {
        "idx_str_1": "title",
        "idx_int_1": "done"
      }
    }
  }
}

Pole	Typ	Wymagane	Opis
name	string	tak	Nazwa bazy
code	string	nie	Unikalny slug do URL-i (np. “todo” -> /noe/db/todo/...)
app_id	uuid	nie	Powiązana aplikacja Noe (widoczne w “Powiązaniach”)
schema	object	nie	Pola + mapowanie indeksów
public_methods	object	nie	Operacje wystawione bez autoryzacji (niżej)

Typy pól w schema

string, text, integer, number, boolean, datetime, date, time

Indeksy (szybkie wyszukiwanie/filtrowanie)

Indeks	Typ
idx_str_1..3	string (max 255 znaków)
idx_int_1..2	bigint
idx_time_1..2	datetime

Dwa sposoby definiowania indeksów:

• "indexes": { "idx_str_1": "title" } - jawne mapowanie pole -> kolumna indeksu (starszy format)
• "indexed_fields": ["title", "done"] - lista pól, mapowanie na idx_* liczone automatycznie z typu pola (string/text -> idx_str_*, integer/number -> idx_int_*, date/time/datetime -> idx_time_*); pola, które nie mieszczą się w limicie kolumn, po prostu nie są indeksowane

Pola nieindeksowane też są przeszukiwalne (po data->>'pole' w JSONB), tylko wolniej - indeksuj to, po czym naprawdę filtrujesz i sortujesz.

Baza wielotabelowa (tables)

Jedna baza Noe może trzymać kilka “tabel” - każda z własnymi polami i własnymi indeksami. Rekordy rozdziela kolumna table_name.

POST /noe/dbs.json
{
  "db": {
    "name": "Sklep",
    "code": "sklep",
    "schema": {
      "tables": {
        "users": {
          "fields": {
            "name": { "type": "string", "required": true },
            "email": "string",
            "age": "number"
          },
          "indexed_fields": ["name", "email"]
        },
        "orders": {
          "fields": {
            "order_number": "string",
            "user_id": "number",
            "total_amount": "number"
          },
          "indexed_fields": ["order_number", "user_id"]
        }
      }
    }
  }
}

Zasady:

• "fields" przyjmuje skrót "email": "string" albo pełny zapis { "type": "string", "required": true }
• indeksy są liczone per tabela - name w users i order_number w orders oba trafiają do idx_str_1 (to ta sama kolumna, ale rekordy różnych tabel nigdy się nie mieszają, bo zapytania są zawsze zawężone do table_name). Każda tabela ma więc pełny limit: 3 stringi, 2 inty, 2 daty
• required obowiązuje tylko w obrębie swojej tabeli - pole wymagane w users nie blokuje zapisu w orders
• typy pól są walidowane globalnie (ta sama lista typów co w bazie jednotabelowej)
• format jednotabelowy (fields + indexes/indexed_fields na górnym poziomie) działa bez zmian; rekordy takiej bazy mają table_name = null
• nie mieszaj formatów - albo tables, albo fields na górnym poziomie

Rekordy (prywatne - wymaga autoryzacji)

POST /noe/dbs/todo/records.json
{ "record": { "data": { "title": "Zadanie", "done": 0 } } }

W bazie wielotabelowej podaj table_name - decyduje, wg której tabeli rekord jest walidowany i indeksowany:

POST /noe/dbs/sklep/records.json
{ "record": { "table_name": "orders", "data": { "order_number": "Z/2026/01", "user_id": 7 } } }

Aktualizacja: PATCH /noe/dbs/todo/records/:id.json z { "record": { "data": { "done": 1 } } } (w bazie wielotabelowej przekaż też table_name, inaczej rekord wróci do tabeli null). Wyszukiwanie: GET /noe/dbs/todo/search.json?q=fraza&sort=-created_at&filter[done]=0&limit=50.

Wyszukiwanie (/noe/dbs/:db_id/search.json)

Parametr	Opis
table_name	tabela w bazie wielotabelowej - wymagany, gdy schema ma tables
q	szukana fraza; * i % działają jak wildcard (ab* -> ab%), bez nich szuka fragmentu
search_in	pola do przeszukania (lista po przecinku); domyślnie pola indeksowane, a przy braku schematu całe data
filter[pole]	dokładne dopasowanie z konwersją typu ze schematu; wartość z */% przechodzi na ILIKE
sort	pole sortowania, prefiks - = DESC (id, created_at, updated_at, pole indeksowane lub pole z data)
fields	które pola zwrócić (poza id, created_at, updated_at, które są zawsze)
limit / offset	paginacja (limit 1-100, domyślnie 20)

GET /noe/dbs/sklep/search.json?table_name=users&q=ali*&search_in=name&fields=name,email&sort=-created_at&limit=20

Odpowiedź to płaska tablica rekordów (bez total): [{ "id": ..., "created_at": ..., "updated_at": ..., "name": "Alice", ... }].

Brakujące lub nieznane table_name w bazie wielotabelowej daje 400 z listą dostępnych tabel:

{ "error": "table_name is required for multi-table database. Available: users, orders",
  "available_tables": ["users", "orders"] }

Metody publiczne (bez autoryzacji)

public_methods na bazie wystawia operacje pod POST /noe/db/:db_code/:method_name - główny sposób, w jaki frontendy aplikacji Noe czytają/zapisują dane (bez tokenów w kodzie appki).

Operacja	Parametry
list	limit, offset
get	id
create	{ "data": {...} }
update	{ "id": ..., "data": {...} }
delete	{ "id": ... }
search	q, limit, offset, sort, table_name

Konfiguracja per operacja (true = bez ograniczeń, albo obiekt):

Opcja	Opis
allowed_fields	tylko te pola przejdą z requestu (reszta ignorowana)
required_fields	wymagane pola - błąd gdy brakuje
default_values	wartości dopisywane automatycznie (nadpisują brakujące)
auto_fields	pola wypełniane przez serwer - nie do podrobienia przez klienta
allowed_params	dozwolone parametry (dla search)
scope_by	filtrowanie wyników po polu (każdy widzi swoje rekordy)

Zmienne w auto_fields: {ip} (adres IP), {cookie_key} (token per przeglądarka, cookie 1 mies.), {user_id} / {user_name} (zalogowany użytkownik; puste bez sesji).

Przykład - publiczna lista + kontrolowany zapis:

{
  "db": {
    "public_methods": {
      "list": { "scope_by": "user_ip" },
      "create": {
        "allowed_fields": ["title", "done"],
        "required_fields": ["title"],
        "default_values": { "done": 0 },
        "auto_fields": { "user_ip": "{ip}", "author": "{user_name}" }
      }
    }
  }
}

Uwagi:

• auto_fields ZAWSZE nadpisuje pole wartością serwera - jeśli rekordy zapisuje też backend (np. flow przez konektor), nie używaj auto_fields na polach, które backend ustawia sam
• odpowiedzi list/get/create: { "id": ..., "data": {...}, "created_at": ..., "updated_at": ... } (list: tablica, najnowsze pierwsze); czas utworzenia rekordu = created_at
• scope_by dobiera zmienną z auto_fields tego pola (IP albo cookie_key)
• bazy wielotabelowe: table_name przechodzi tylko przez publiczne search. list/get/create/ update/delete nie znają tabel - create zapisze rekord z table_name = null (bez walidacji i indeksów tabeli), a list/get widzą rekordy ze wszystkich tabel wymieszane. Frontend appki, który ma czytać/pisać konkretną tabelę, korzystaj z prywatnego API rekordów (z tokenem), z publicznego search z table_name, albo trzymaj tabelę jako osobną bazę jednotabelową
• filter[pole] i fields obsługuje tylko prywatny /noe/dbs/:db_id/search.json - w publicznym search zostają q, sort, table_name, limit, offset

Replace API (częściowa edycja)

PATCH /noe/dbs/:id/replace.json
{ "field": "public_methods", "old_string": "\"list\": true", "new_string": "\"list\": { \"scope_by\": \"user_ip\" }" }

Dozwolone pola: fields, schema, public_methods. Opcja replace_all: true dla wielu wystąpień.

Powiązane

• noe_api - API aplikacji Noe (akcje, silniki, źródła)
• noe_app_example_weather - kompletny przykład: appka + baza z publicznymi metodami + flow + cron
• common_api - wspólne zasady API