7 Collections
Anton Nesterov edited this page 2026-11-08 20:25:29 +01:00

Collections

Collections are the primary way to structure and organize your data in VSKI. Each collection has a schema that defines the fields and their types.

Collections can live in in different databases, but collection metadata is stored in the default database.

Creating Collections

Collections are declared, not created imperatively: the schema lives in YAML and vski apply turns changes into reviewable, rollback-able server-side migrations (see IaC).

Basic Collection

# vski/default/collections.yaml
version: 1
database: default

collections:
  posts:
    type: base
    fields:
      - {name: title, type: text, required: true}
      - {name: content, type: text}
      - {name: published, type: bool}
      - {name: views, type: number}
vski plan      # + collection default/posts (create base table with 4 fields)
vski apply     # creates it via a migration

Scaffolding a new project? vski setup writes a starter file exactly like this one.

Field Types

Type Description Example
text Plain text string "Hello"
email Email address "user@example.com"
number Numeric value 42 or 3.14
bool Boolean value True or False
date Date string "2024-01-01"
datetime Datetime with timezone "2024-01-01T00:00:00Z"
select Predefined options Use with values: [...]
url URL string "https://example.com"
editor Rich text content HTML/Markdown content
json JSON object { "key": "value" }
relation Reference to another collection Use with collectionId

Auth Collections

collections:
  _users:
    type: auth
    fields:
      - {name: email, type: email, required: true}
      - {name: password, type: text, required: true}
      - {name: name, type: text}

Auth collections automatically include system fields (id, created, updated). Fields whose names start with _ are internal and never managed by IaC.

When declaring a collection you write fields:; when reading collection metadata back the server returns the schema as schema:. Same data, different key on the wire.

Creating Records

Runtime data operations use the Python SDK (pip install vski-sdk; see SDK Installation):

import asyncio
from vski import VskiClient

async def main():
    async with VskiClient("http://127.0.0.1:3000") as client:
        res = await client.admins.auth_with_password(
            "admin@yourdomain.com", "your-password"
        )
        client.set_token(res["token"])

        post = await client.collection("posts").create(
            {"title": "Hello World", "content": "My first post",
             "published": True, "views": 0}
        )
        print(post["id"])       # auto-generated
        print(post["created"])  # auto timestamp

asyncio.run(main())

For quick one-offs the command line does the same:

vski records create posts '{"title": "Hello World", "published": true}'
vski records list posts --filter 'published = true'

Using Custom ID

post = await client.collection("posts").create(
    {"id": "custom-post-id", "title": "Custom ID Post", "content": "..."}
)

Reading Records

Get Single Record

post = await client.collection("posts").get_one("record-id")
print(post["title"])

List Records

page = await client.collection("posts").get_list(1, 20)
print(page["totalItems"])   # total number of records
print(page["items"])        # records on this page
print(page["totalPages"])   # total pages

Skipping Totals (Fast Lists)

Every list request normally runs a COUNT(*) to fill totalItems/totalPages, which scans the whole table on large collections. Add skipTotal=true to skip it; both totals come back as -1 (unknown). Ideal for infinite-scroll UIs that only need the next page:

GET /api/collections/posts/records?page=1&perPage=30&skipTotal=true
{ "page": 1, "perPage": 30, "totalItems": -1, "totalPages": -1, "items": [ ... ] }

Filter Records

page = await client.collection("posts").get_list(
    1, 20, filter="published = true AND views > 10"
)

Sort Records

newest = await client.collection("posts").get_list(1, 20, sort="-created")
multi = await client.collection("posts").get_list(1, 20, sort="-published,created")

Updating Records

updated = await client.collection("posts").update(
    "record-id", {"title": "Updated Title", "views": 100}
)
# updates are partial: unchanged fields keep their values
partial = await client.collection("posts").update("record-id", {"title": "Just the title"})

Deleting Records

ok = await client.collection("posts").delete("record-id")   # True

Query Filters

Filters are SQL-like expression strings:

get = lambda **kw: client.collection("posts").get_list(1, 20, **kw)

# Comparison: =  !=  >  <  >=  <=
await get(filter="views > 100")

# Logical: AND, OR, parentheses for grouping
await get(filter="(status = 'active' OR status = 'pending') AND published = true")

# Strings: ~ is a substring match (LIKE with wildcards added automatically)
await get(filter="title ~ 'Hello'")

# Null checks
await get(filter="deleted = null")
await get(filter="deleted != null")

# JSON/array fields
await get(filter="tags ~ ['python', 'vski']")
await get(filter="tags ~ 'python'")

Pagination

page1 = await client.collection("posts").get_list(1, 20)
page2 = await client.collection("posts").get_list(2, 20)
if page1["page"] < page1["totalPages"]:
    ...  # more pages available

Expand Relations

When you have relation fields, you can expand them:

post = await client.collection("posts").get_one("post-id", expand="author,category")
print(post["expand"]["author"])    # full author record
print(post["expand"]["category"])  # full category record

Collection Management

Schema changes (add/remove fields, indexes, rules, FTS) belong in the YAML; vski apply diffs desired against live and emits the migration. To drop a collection, mark it state: absent (or delete it with vski collections rm, which removes the table immediately).

collections:
  old_posts:
    state: absent

Inspecting what exists:

vski collections list
vski collections show posts        # fields, rules, indexes, views

Reading collection metadata from the SDK:

result = await client.settings.collections.get_list()
posts = next(c for c in result["items"] if c["name"] == "posts")
print(posts["schema"])

Warning: Deleting a collection deletes all its records.

Best Practices

  1. Use meaningful field names: follow consistent naming conventions
  2. Set required fields: use required: true for essential data
  3. Index frequently queried fields: improve query performance
  4. Use appropriate types: choose the most specific type for your data
  5. Validate on client side: reduce unnecessary API calls
  6. Use pagination: always use get_list() with limits for large datasets

API Endpoints

Method Endpoint Description
GET /api/collections List collections
POST /api/collections Create collection
GET /api/collections/:name Get collection
PATCH /api/collections/:name Update collection
DELETE /api/collections/:name Delete collection
GET /api/collections/:name/records List records
POST /api/collections/:name/records Create record
GET /api/collections/:name/records/:recordId Get record
PATCH /api/collections/:name/records/:recordId Update record
PUT /api/collections/:name/records/:recordId Update record (full)
DELETE /api/collections/:name/records/:recordId Delete record
PATCH /api/collections/:name/records/bulk Bulk update records
DELETE /api/collections/:name/records/bulk Bulk delete records
GET /api/collections/:name/records/search Full-text search records
GET /api/collections/:name/records/views/:slug Get records from view