Kanesh
GitHub ★ Star

Operasional

Impor dan ekspor

Ekspor record JSON atau CSV dengan batas terukur dan impor record tervalidasi secara atomik.

Setelah membaca panduan ini, kamu akan tahu cara mentransfer record koleksi sebagai JSON atau CSV dan data yang memerlukan backup terpisah.

1. Ekspor record yang cocok

Gunakan GET /api/v1/workspaces/:workspace/collections/:collection/records/export?format=json. Untuk CSV, gunakan format=csv. Opsi query record yang sudah ada tetap berlaku; include_system=true menyertakan ID dan timestamp.

Ganti placeholder workspace, koleksi, dan token. Contoh ini mengasumsikan koleksi memiliki field title:

curl --get 'http://127.0.0.1:8080/api/v1/workspaces/YOUR_WORKSPACE/collections/YOUR_COLLECTION/records/export' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --data-urlencode 'format=json' \
  --data-urlencode 'include_system=true' \
  --data-urlencode 'query={"fields":["title"],"sort":[{"field":"title","descending":false}]}'

Ekspor dibatasi hingga 1.000 record dan 1 MiB. Ekspor gagal jika batas terlampaui.

Note: Ekspor berupa pembacaan berpaginasi, bukan backup transaksional. Lihat Backup dan upgrade untuk penyimpanan persisten.

2. Impor record baru secara atomik

Gunakan POST /api/v1/workspaces/:workspace/collections/:collection/records/import. Body JSON memiliki format (json atau csv), string content, dan ignore_read_only:

{
	"format": "csv",
	"content": "title\nExample record\n",
	"ignore_read_only": false
}

Untuk koleksi dengan field title yang bisa ditulis dan tanpa input wajib lainnya:

curl -X POST 'http://127.0.0.1:8080/api/v1/workspaces/YOUR_WORKSPACE/collections/YOUR_COLLECTION/records/import' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"format":"csv","content":"title\nExample record\n","ignore_read_only":false}'

Impor membuat 1–100 record tervalidasi secara atomik. File setelah dekode dan body permintaan JSON masing-masing dibatasi 1 MiB. ID dan timestamp baru dihasilkan. ID referensi dipertahankan tanpa pemetaan ulang.

Metadata read-only ditolak kecuali secara eksplisit diabaikan dengan ignore_read_only: true. Field yang tidak dikenal tetap tidak valid meskipun metadata read-only diabaikan.

3. Siapkan konten CSV

  • Gunakan UTF-8, pemisah koma, dan quoting CSV standar.
  • Header harus unik dan cocok dengan skema koleksi.
  • Gunakan true atau false untuk boolean dan sintaks angka JSON untuk angka.
  • Encode field JSON sebagai sel JSON, dengan quoting CSV bila diperlukan.
  • Gunakan \N untuk null. Teks kosong tetap berupa teks kosong.
  • Escape backslash di awal dan teks berawalan formula dengan menambahkan backslash di depannya.

Note: Escape backslash ini merupakan konvensi Kanesh. Utamakan JSON untuk transfer tanpa kehilangan informasi.

4. Perhitungkan data yang tidak disertakan

Transfer CSV/JSON menyertakan ID file, bukan upload biner atau link relasi. Impor hanya membuat record: tidak melakukan upsert, menulis relasi bersarang, atau membuat foreign key/junction. ID referensi yang dipertahankan tidak dipetakan ulang ke ID record yang baru dihasilkan.

Pemecahan masalah

  • Ekspor melampaui batas: persempit record yang cocok atau field hasil agar tetap dalam batas 1.000 record dan 1 MiB.
  • Impor ditolak: periksa rentang 1–100 record, kedua batas 1 MiB, nama field, dan input wajib.
  • File ekspor dengan system field tidak bisa diimpor: atur ignore_read_only: true secara eksplisit jika kamu ingin membuang metadata tersebut dan menghasilkan nilai baru.
  • File atau relasi tidak muncul setelah transfer: file biner dan link relasi berada di luar kontrak transfer.

Note: Integrasi transfer sudah diverifikasi di SQLite. Pemeriksaan runtime PostgreSQL/MySQL masih tertunda.

Langkah berikutnya

Traktir kopi