MESA Core · v0.9.3
Arama görünümlerini yeniden oluşturma
Bu rehberin Türkçe ve İngilizce sürümleri aynı konuyu açıklar. Bu sayfayla ilgili kaynak bölümleri en altta yer alır.
Yeniden oluşturmanın kapsamını bilin#
Bu işlem varsayılan olarak kapalıdır ve yalnızca ADMIN yetkisiyle kullanılabilir. Veri dizininin tamamını kapsar. İsteğin kabul edilmesi, kontrol noktalarıyla çevrimdışı yeniden yürütme, doğrulama ve yeni düzene geçiş ayrı aşamalardır. Özellik kapalıysa 501, desteklenmeyen kapsam istenirse 409 döner. Asıl kayıtların sahipliğini ve yedeği koruyun. Bu işlemi tek bir üst erişim alanını çevrimiçi onarma yöntemi olarak kullanmayın.
İşlem adımlarını özgün kaynaktan izleyin#
Bütün seçenekler ve yönetim koşulları aşağıdaki kaynakta yer alır. Öncesinde mimari, API, işletim ve sürüm sınırları belgelerini okuyun.
Kaynak belgedeki ilgili bölümler
Bu bölüm, kaynak belgenin bu sayfayla ilgili kısımlarını değiştirmeden gösterir. Kaynak içindeki bir bölüme giden bağlantıyı açtığınızda metin otomatik olarak görünür.
Bu prosedür mevcut V4 storage-root-wide projection rebuild içindir; tasarım
ADR 0014 ile başlamıştır.
LanceDB ve Kùzu generation'ları mevcut canonical V4 snapshot'tan üretilir;
V3 verisini dönüştürmez ve canonical source/assertion içeriğini yeniden yazmaz.
FTS integrity snapshot üzerinde doğrulanır. SQLite operation/checkpoint ve
active-generation kayıtları güncellenir; başarılı cutover sonrası representation
metadata'sı da aşağıda açıklanan kuralla ilerletilir. Açık adopt-provider
adımı ayrıca eksik provenance metadata'sını tamamlayabilir.
Tenant, workspace veya dataset kapsamlı rebuild desteklenmez.
Güvenlik sınırları ve ön koşullar#
MESA_V4_REBUILD_ENABLEDvarsayılan olarakfalsekalır. Yalnız onaylı
rehearsal/değişiklik penceresinde API ve runner için true yapın.
- API işlemleri principal'a bağlı credential ve control-plane
ADMINrolü
ister. Dataset rolleri tek başına yeterli değildir.
- Rebuild online değildir. Submit yazma admission'ını kapatır; backlog drain
edildikten sonra combined runtime durdurulur ve runner storage writer
lock'ını tek başına alır.
- Trusted, storage ve work root'ları önceden var olmalı; storage/work trusted
root'un gerçek alt dizinleri olmalı, birbirleriyle örtüşmemeli ve symlink
içermemelidir. Bu path'ler HTTP request'iyle alınmaz.
- Work filesystem'de en az storage boyutunun iki katı ve runner'ın güvenlik
rezervi kadar boş alan bulunmalıdır. Runner kendi ölçümünü yapar ve yetersiz
alanda fail-closed davranır.
- API ile runner aynı provider, embedding model/version ve dimension config'ini
kullanmalıdır. MESA_EMBEDDING_VERSION boş bırakılamaz; dimension gerçek
provider çıktısıyla aynı olmalıdır. Snapshot provenance'ı uyuşmuyorsa runner
rebuild yapmaz.
- Backup ve retained generation otomatik silinmez. Bu release'te otomatik veya
zamanlanmış projection-generation cleanup yoktur.
Başlamadan önce gerçek-provider rehearsal, production-benzeri disk/concurrency
kanıtı ve geri dönüş penceresi için yeterli kapasite doğrulanmalıdır.
1. Operator yetkisini ve flag'i hazırla#
Flag'i combined runtime'ın açık deployment config'inde etkinleştirin:
export MESA_V4_REBUILD_ENABLED=trueMevcut corpus'un doğrulanmış provider/model/version/dimension ayarlarını koruyun.
Burada örnek bir boyut veya sürüm atayarak mevcut embedding kimliğini değiştirmeyin;
yapılandırma ve provenance kayıtları aynı kimliği göstermelidir.
Credential'ı bir kez üretin ve aynı principal'a control-plane rolü verin.
Credential'ı shell history, log veya runbook kaydına kopyalamayın:
export MESA_STORAGE_ROOT=/srv/mesa/v4-data
mesa-v4-admin issue-key --principal rebuild-operator
mesa-v4-admin grant-control --principal rebuild-operatorRuntime yeniden başladıktan sonra capability gerçeğini kontrol edin:
curl --fail \
-H "X-API-Key: $MESA_API_KEY" \
http://127.0.0.1:8000/v4/capabilitycapabilities.durable_rebuild değeri true, limits.rebuild_scope değeri
storage_root ve limits.requires_offline_runner değeri true olmalıdır.
2. Durable operation submit et#
Her değişiklik penceresi için benzersiz, içerik taşımayan bir idempotency key
kullanın:
export MESA_REBUILD_IDEMPOTENCY_KEY="$(.venv/bin/python -c 'import uuid; print(uuid.uuid4())')"
curl --fail-with-body -X POST \
-H "X-API-Key: $MESA_API_KEY" \
-H "Idempotency-Key: $MESA_REBUILD_IDEMPOTENCY_KEY" \
http://127.0.0.1:8000/v4/operations/rebuildBaşarılı durable commit 202 ve PENDING operation döndürür. Aynı key ve aynı
sabit storage-root payload aynı operation'ı döndürür. Çakışan payload veya aynı
root'ta başka aktif rebuild 409 olur. Idempotency-Key zorunludur.
Yanıttaki operation_id değerini secret olmayan incident/change kaydına alın:
export MESA_REBUILD_OPERATION_ID=00000000-0000-4000-8000-000000000000Submit sonrası v4 mutation endpoint'leri 503 maintenance_pending ve
Retry-After: 5 döndürür. Read, capability, health, metrics ve operation status
açık kalır. RETRYABLE_FAILED da maintenance admission'ını kapalı tutar.
3. Backlog'u drain et#
Combined runtime'ı henüz durdurmadan /health ile özet durumu ve
/health/init ile readiness'i kontrol edin. /metrics üzerinden sunulan
kuyruk sayaçlarını izleyin; aşağıdaki tüm backlog koşulları offline runner'ın
preflight kontrolünde yeniden doğrulanır:
- projection backlog ve dead letter;
- cleanup backlog ve blocked cleanup;
- stuck/in-flight projection lease;
- dispatch/raw-log işleri, vector WAL ve session finalization işleri.
Özellikle mesa_v4_projection_backlog,
mesa_v4_projection_dead_letter, mesa_v4_projection_stuck_leases,
mesa_v4_cleanup_backlog ve mesa_v4_cleanup_blocked sıfır olmalıdır. Runner
canonical SQLite'taki tüm kuyrukları ve storage-root DLQ dosyasını tekrar
kontrol eder; sıfır olmayan herhangi bir değer rebuild'i reddeder. Kuyruk
kaydını veya lease'i elle silerek preflight'ı atlamayın.
4. Combined runtime'ı durdur ve offline runner'ı çalıştır#
Backlog sıfırlandıktan sonra combined process'i kontrollü durdurun. Process'in
storage writer lock'ını bıraktığını doğrulayın. Sonra aynı reviewed provider
config'iyle şu komutu çalıştırın:
fd4e5f6a7b8c öncesinde oluşturulmuş aktif vector mutation'larında provider
kimliği eksikse normal runner fail-closed olur. Adoption yalnız henüz hiç claim
edilmemiş (attempt_count=0), source_manifest_hash yazılmamış fresh PENDING
operation üzerinde yapılabilir. Combined runtime durmuş ve
provider/model/version/dimension eski generation'ı üreten config kayıtlarından
dışarıdan doğrulanmışsa bir kez şu açık adoption adımını çalıştırın:
mesa-v4-rebuild adopt-provider \
--trusted-root /srv/mesa \
--storage-root /srv/mesa/v4-data \
--provider openai_compatible \
--model text-embedding-3-small \
--version "$MESA_EMBEDDING_VERSION" \
--dimension "$MESA_EMBEDDING_DIMENSION" \
--confirm-legacy-provider-unknownBu komut rebuild değildir: yalnız aktif vector ownership'ine bağlı canonical
mutation satırlarındaki eksik provider alanlarını COALESCE ile tamamlayan,
writer-lock korumalı ve açık operator onayı isteyen tek seferlik metadata
adoption işlemidir. Var olan herhangi bir provider/model/version/dimension
değeri assertion ile çelişirse transaction bütünüyle geri alınır. Bu kanıt
yoksa adoption yapmayın; release NO-GO kalır ve sonraki full raw-source
rebuild iş paketini bekleyin. mesa-v4-rebuild run, aşağıda açıklanan doğrulanmış
assertion-vector representation işareti dışında canonical içerik kayıtlarını
değiştirmez.
Bir rebuild denemesi başladıysa adoption canonical manifest'i değiştirebileceği
için aynı backup/checkpoint ile resume güvenli değildir ve komut fail-closed
olur. Bu kural source_manifest_hash henüz yazılmadan oluşan crash penceresini
de kapsar; hiçbir RETRYABLE_FAILED operation üzerinde adoption yapılmaz. Eski
operation'ı cancel edin, yeni bir Idempotency-Key ile fresh rebuild submit
edin, backlog'u yeniden drain edip runtime'ı durdurun ve adoption'ı yeni
PENDING operation üzerinde runner'dan önce çalıştırın. Eski operation'ın
backup veya checkpoint'ini yeni operation'da kullanmayın.
Ardından aynı reviewed provider config'iyle normal runner'ı çalıştırın:
mesa-v4-rebuild run \
--trusted-root /srv/mesa \
--storage-root /srv/mesa/v4-data \
--work-root /srv/mesa/rebuild-work \
--operation-id "$MESA_REBUILD_OPERATION_ID"İsteğe bağlı --batch-size sınırı 1..1000, --lease-seconds sınırı
30..3600 arasındadır. Runner sırasıyla writer lock, Alembic head, fenced
operation lease, backlog, path/symlink, disk, checksummed backup, source
manifest, provider provenance, deterministic vector/graph replay, parity ve
cutover kontrollerini yürütür.
Assertion-vector representation geçişi#
Alembic yükseltmesi mevcut ASSERTION_VECTOR kayıtlarını açıkça legacy-v0
olarak işaretler. Runtime, yalnız assertion-semantic-v1 representation
sürümüne sahip vector kayıtlarını semantic lane'e kabul eder; eksik, bozuk veya
karma sürümlü metadata fail-closed davranır. Yeni ingestion/reprojection aynı
fiziksel assertion ID'sini upsert eder ve hem receipt hem registry metadata'sını
güncel sürümle değiştirir.
Mevcut corpus için desteklenen reindex yolu tam, offline
mesa-v4-rebuild run akışıdır. Replay kaynağı yalnız canonical SQL assertion
alanlarıdır ve payload subject + predicate + object + tam evidence span'dan
deterministik olarak yeniden üretilir; entity/chunk vector'ları assertion
kanıtı gibi taşınmaz. Eski aktif generation çalışırken legacy-v0 kayıtları
semantic lane'e katılmaz. Registry'deki representation sürümü ancak parity,
atomic cutover ve post-cutover health/smoke doğrulaması başarılı olduktan sonra
assertion-semantic-v1 yapılır. Başarısız veya yarım staging generation bu
işareti ilerletemez; aynı operation'ın crash-resume akışı işareti idempotent
olarak yeniden yayımlar.
Exit code'lar:
| Code | Anlam | Operator işlemi |
|---|---|---|
0 | COMPLETED | Runtime'ı yeniden başlatma adımına geçin |
2 | Flag/config/operation reddi | Config ve operation status'unu düzeltin; kör retry yapmayın |
3 | Güvenli retryable failure | Status/checkpoint'i inceleyip aşağıdaki resume akışını kullanın |
4 | Başka writer aktif | API/worker/combined process'i bulun; ikinci writer başlatmayın |
5 | Retry bütçesi tükendi, FINAL_FAILED | Rehearsal'ı durdurun; yeni operation öncesi kök nedeni giderin |
Runner stdout/stderr çıktısı operation/generation/state/count/error-class ile
sınırlıdır. Fiziksel path, içerik, credential, manifest payload veya claim
token loglanmamalıdır.
5. Resume, retry ve cancel#
Kontrollü hata RETRYABLE_FAILED üretmişse aynı durable operation ve checkpoint
üzerinde önce retry isteği gönderin, sonra aynı runner komutunu çalıştırın:
curl --fail-with-body -X POST \
-H "X-API-Key: $MESA_API_KEY" \
"http://127.0.0.1:8000/v4/operations/$MESA_REBUILD_OPERATION_ID/retry"API bunun için geçici olarak yeniden başlatılmışsa runner'dan önce tekrar
durdurulmalıdır. retry yalnız RETRYABLE_FAILED durumunda 202 döndürür ve
checkpoint'i silmez. Retry budget tükenirse 409 döner.
Process SIGKILL, host crash veya güç kaybıyla aktif durumda kesildiyse API
retry çağrısı yapmayın. Lease süresi dolduktan sonra aynı runner komutu stale
owner'ı yeni fencing token ile reclaim eder. Tamamlanmış batch'ler yalnız source
manifest değişmemişse kullanılır. Crash READY_TO_CUTOVER sırasında olduysa
runner pointer değişmemiş veya target'a değişmiş iki güvenli durumu ayırır;
replay yapmadan yeniden doğrular, tamamlar ya da retained source'a döner.
Operasyondan vazgeçmek yalnız PENDING veya RETRYABLE_FAILED için güvenlidir:
curl --fail-with-body -X POST \
-H "X-API-Key: $MESA_API_KEY" \
"http://127.0.0.1:8000/v4/operations/$MESA_REBUILD_OPERATION_ID/cancel"CANCELLED eski active generation ile mutation admission'ını yeniden açar.
Staging generation ve backup otomatik silinmez. CLAIMED, RUNNING,
VERIFYING veya READY_TO_CUTOVER operation'ını cancel etmeye çalışmak 409
olur; runner'ı önce güvenli batch sınırında durdurun.
6. Cutover, otomatik rollback ve restart#
Pre-cutover parity başarısızsa pointer değiştirilmez. Parity geçerse vector ve
graph birlikte tek SQLite generation pointer transaction'ıyla aktive edilir.
Post-cutover reopen/health/smoke başarısızsa runner pointer'ı retained source
generation'a otomatik döndürür, rollback'i tekrar doğrular ve operation'ı
RETRYABLE_FAILED yapar.
Bu release tamamlanmış operation için manuel HTTP rollback endpoint'i sunmaz.
COMPLETED sonrası yeni generation'da incident görülürse tüm writer'ları
durdurun; pointer tablolarını veya generation dizinlerini elle değiştirmeyin.
Backup/retained generation'ı koruyun ve recovery prosedürüyle incident
escalation yapın. Geç activation crash'i aynı operation'ın reclaim akışıyla
otomatik olarak tamamlanır veya geri alınır.
Runner 0 döndürdükten ya da operation güvenle cancel edildikten sonra combined
runtime'ı yeniden başlatın. Status'u control-plane ADMIN credential ile
doğrulayın:
curl --fail \
-H "X-API-Key: $MESA_API_KEY" \
"http://127.0.0.1:8000/v4/operations/$MESA_REBUILD_OPERATION_ID"Yetkisiz status/cancel/retry çağrıları operation varlığını sızdırmamak için
404 döndürür. Status yalnız kind/scope/state/attempt, progress, bounded
error-class ve zaman alanlarını içerir.
Tamamlanmış değişiklik penceresinden sonra yeni submit/retry gerekmiyorsa flag'i
tekrar false yapıp reviewed config ile runtime'ı yeniden başlatın. Existing
operation status ve health flag kapalıyken de okunabilir.
7. Gözlemlenebilirlik ve retained artifact'lar#
İzlenecek rebuild metrikleri:
mesa_v4_rebuild_operation_state{state=...};mesa_v4_rebuild_duration_seconds;mesa_v4_rebuild_progress_completedve
mesa_v4_rebuild_progress_total;
mesa_v4_rebuild_parity_missing;mesa_v4_rebuild_staging_bytes;mesa_v4_rebuild_rollbacks_total.
/health yalnız status, maintenance ve rebuild_state özetini verir;
ayrı bir rebuild ayrıntı nesnesi içermez. Duration, progress ve rollback
sayaçları /metrics üzerinden okunur. Operation ayrıntıları yetkili
/v4/operations/{operation_id} endpoint'indedir. FINAL_FAILED degraded;
aktif ve RETRYABLE_FAILED durumları maintenance kabul edilir.
Backup, failed staging generation ve retained generation için ayrı change
record tutun. Bu release'te hiçbirini otomatik silmeyin. Silme/retention
politikası sonraki açık operator iş paketidir.
8. API/SDK sınırı ve production kararı#
Deprecated POST /v4/rebuild yalnız storage-root alias'ıdır. tenant_id,
workspace_id veya dataset_id verilirse 409 döner. Dataset-bound MCP
araçları global rebuild submit/cancel/retry sunmaz. Sync ve async Python
SDK'lar capability, submit_rebuild, operation_status, cancel_operation
ve retry_operation metotlarını sunar.
Merge, unit/integration test veya CI evidence tek başına production GO
değildir. Aşağıdakilerin tamamı aynı release adayıyla tamamlanana kadar karar
NO-GO kalır:
- gerçek LanceDB/Kùzu ve seçilen embedding provider ile backup → rebuild →
reopen → parity → rollback rehearsal;
- production-benzeri disk kapasitesi, dataset büyüklüğü ve concurrency;
- migration/DR ve content-free closure evidence artifact'ları;
- cross-tenant/dataset negatif retrieval ve crash/fencing kanıtı;
- kesintisiz 24 saat soak ve operasyon onayı.
