Redis Search: FT.CREATE ile İndeks Oluşturma ve FT.SEARCH ile Sorgulama

Redis Search hangi sorunu çözer?

Redis bir anahtar-değer deposudur: bir değeri bulmak için anahtarını bilmeniz gerekir. "Fiyatı 500 ile 1000 arasında olan yeni ürünler" veya "açıklamasında çocuk geçen kayıtlar" gibi bir soru sorduğunuzda saf Redis komutlarıyla yapabileceğiniz şey, anahtarları SCAN ile dolaşıp her birini istemcide süzmek ya da her sorgu için elle bakımını yaptığınız sorted set indeksleri tutmaktır. İlki veri büyüdükçe pahalılaşır (ayrıntı için SCAN ve KEYS yazısı), ikincisi ise her yazma işleminde indeksleri de güncellemeyi uygulamanın sorumluluğuna bırakır. Sorted set belgesi de veriyi indeksleyip sorgulamak istiyorsanız JSON ile Redis Search kullanmayı önerir.

Redis Search bu bakımı sunucuya taşır. Belgeye göre özellik Redis'i bir belge veritabanı, vektör veritabanı, ikincil indeks ve arama motoru olarak kullanmanıza imkan verir. İndeks artımlı çalışır: indeks oluşturulduğu anda var olan belgeler arka planda, eşzamansız olarak indekslenir; bu yüzden büyük bir veri kümesinde tüm belgelerin sorgularda görünmesi biraz zaman alabilir. İndeks kurulduktan sonra eklenen veya değiştirilen belgeler ise eşzamanlı indekslenir, yani yazma komutu döndüğünde belge sorgulanabilir durumdadır. Uygulamanızın ayrıca "indeksi güncelle" adımı çalıştırmasına gerek kalmaz.

FT.CREATE ile indeks oluşturma

FT.CREATE komutunun gövdesi üç bölümden oluşur. Önce indeksin adı gelir; aynı adda bir indeks zaten varsa komut hata döndürür. Ardından isteğe bağlı ON HASH veya ON JSON ile hangi veri tipinin indeksleneceğini söylersiniz; varsayılan HASH'tir. PREFIX ile hangi anahtar öneklerinin indekse gireceğini belirtirsiniz: ilk sayı kaç önek verdiğinizi gösterir, sonra önekler sıralanır. PREFIX verilmezse varsayılan tüm anahtarlardır. Son olarak SCHEMA anahtar kelimesinden sonra her alan için tanımlayıcıyı, isteğe bağlı AS takma adını ve alan türünü yazarsınız.

Komut sayfasındaki ilk örnek, anahtarı blog:post: ile başlayan blog yazısı hash'lerinin başlığını, yayın tarihini ve kategorisini indeksler:

> FT.CREATE idx ON HASH PREFIX 1 blog:post: SCHEMA title TEXT SORTABLE published_at NUMERIC SORTABLE category TAG SORTABLE
OK

Burada title tam metin araması yapılacak bir alan, published_at aralık sorgusu yapılacak sayısal bir alan, category ise tam eşleşmeyle süzülecek bir etiket alanıdır. Üçüne de eklenen SORTABLE, sonuçları bu alana göre sıralamayı çok düşük gecikmeyle yapabilmek içindir. Aynı komutu ikinci kez çalıştırırsanız komut sayfasının belirttiği hata döner:

(error) Index already exists

Hash için tanımlayıcı, hash içindeki alanın adıdır. Aynı hash alanını iki farklı türde indekslemek de mümkündür; belgedeki örnekte sku alanı hem sku_text adıyla TEXT hem de sku_tag adıyla TAG olarak indekslenir. Bir indeks birden fazla öneki kapsayabilir: PREFIX 2 author:details: book:details: yazarak yazar ve kitap hash'lerini aynı indekste toplayabilirsiniz. Anahtar adlandırma düzeninin burada ne kadar önemli olduğunu görmek için anahtar isimlendirme yazısına göz atın; önek temelli indeksleme, tutarlı nesne:id adlarıyla çok daha kolay yönetilir.

Alan türleri

Vektör alanları ve KNN sorguları bu yazının konusu değil; yalnızca belgelerin vektör aramayı ayrı bir başlık altında ele aldığını ve VECTOR türünün en az 2. sorgu diyalektini gerektirdiğini bilmeniz yeterli. Coğrafi sorgularda değer önce boylam sonra enlem olacak şekilde virgülle ayrılmış bir dizgidir; Redis'in kendi coğrafi komutları için GEOADD ve GEOSEARCH yazısına bakabilirsiniz.

Alan seçenekleri

• SORTABLE: NUMERIC, TAG, TEXT ve GEO alanlarında sonuçları bu alana göre hızlı sıralamayı sağlar. Bellek maliyeti vardır; komut sayfası büyük metin alanlarında kullanmamayı önerir. SORTABLE olmadan da sıralama yapılabilir, ancak gecikme daha yüksektir.
• UNF: Hash belgelerinde SORTABLE, değeri normalleştirir (küçük harfe çevirir, aksan işaretlerini kaldırır). UNF bu normalleştirmeyi kapatır. JSON belgelerinde SORTABLE ile UNF zaten örtük olarak uygulanır.
• NOSTEM: TEXT alanında kök bulmayı (stemming) kapatır; özel isimler için uygundur.
• NOINDEX: Alanı indekslemez. SORTABLE ile birlikte kullanıldığında yalnızca sıralama için tutulan bir alan elde edersiniz; SORTABLE yoksa alan tamamen yok sayılır.
• WEIGHT: TEXT alanının sonuç alaka puanındaki ağırlığıdır, varsayılanı 1'dir.
• SEPARATOR ve CASESENSITIVE: TAG alanında değerin hangi tek karakterle parçalara ayrılacağını (varsayılan virgül) ve harf büyüklüğünün korunup korunmayacağını belirler. CASESENSITIVE yoksa etiketler küçük harfe çevrilir.
• WITHSUFFIXTRIE: TEXT ve TAG alanında sonek ve "içerir" sorgularını hızlandıran bir sonek ağacı tutar.
• INDEXEMPTY ve INDEXMISSING: Search 2.10 ile gelen bu seçenekler, boş dizgileri ve alanı hiç olmayan belgeleri aranabilir yapar. Varsayılan olarak ikisi de indekslenmez.

Türkçe içerik indeksliyorsanız LANGUAGE seçeneği önemlidir. Komut sayfası varsayılan dilin İngilizce olduğunu ve desteklenen diller arasında turkish bulunduğunu belirtir. Dil, indeksleme sırasında hangi kök bulucunun kullanılacağını belirler; belge başına dil seçmek isterseniz LANGUAGE_FIELD ile dili belgenin bir alanından okutabilirsiniz. STOPWORDS ile indeksleme ve arama sırasında yok sayılacak kelimelerin listesini kendiniz verebilir, STOPWORDS 0 ile durdurma kelimelerini tamamen kapatabilirsiniz.

FILTER ile seçici indeksleme

Önek, hangi anahtarların indekse gireceğini kaba biçimde belirler. Daha ince bir seçim için FILTER bir ifade alır ve yalnızca ifadeyi sağlayan belgeleri indeksler. Komut sayfasındaki iki örnek, adı G ile başlayan yazarları ve alt başlığı boş olmayan kitapları indeksler; son örnek ise kategorileri noktalı virgülle ayrılmış bir TAG alanı tanımlar:

FT.CREATE g-authors-idx ON HASH PREFIX 1 author:details FILTER 'startswith(@name, "G")' SCHEMA name TEXT
FT.CREATE subtitled-books-idx ON HASH PREFIX 1 book:details FILTER '@subtitle != ""' SCHEMA title TEXT
FT.CREATE books-idx ON HASH PREFIX 1 book:details SCHEMA title TEXT categories TAG SEPARATOR ";"

JSON belgelerini indekslemek

ON JSON ile oluşturulan bir indekste tanımlayıcılar JSONPath ifadeleridir ve her ifadenin sonucu AS ile verdiğiniz öznitelik adıyla ilişkilendirilir. Belge özniteliğin isteğe bağlı olduğunu söyler, ancak pratikte her alana bir ad vermeniz gerekir; çünkü sorgu ayrıştırıcısı JSONPath ifadelerini tam desteklemez ve FT.SEARCH sorgularında öznitelik adını kullanmanız istenir. Aşağıdaki oturum, tam eşleşme sorguları belgesindeki e-posta örneğidir; içinde özel karakter bulunan bir etiketin çift tırnakla ve 2. diyalektle nasıl aranacağını da gösterir:

> FT.CREATE idx:email ON JSON PREFIX 1 key: SCHEMA $.email AS email TAG
OK
> JSON.SET key:1 $ '{"email": "test@redis.com"}'
OK
> FT.SEARCH idx:email '@email:{"test@redis.com"}' DIALECT 2
1) (integer) 1
2) "key:1"
3) 1) "$"
   2) "{\"email\":\"test@redis.com\"}"

Yanıtın biçimi tüm FT.SEARCH sorgularında aynıdır: ilk eleman eşleşen belgelerin toplam sayısıdır, ardından her belge için anahtar adı ve o belgenin öznitelik-değer çiftlerinden oluşan bir dizi gelir. JSON indeksinde $ adlı alan belgenin tamamını taşır. Belgeye göre 2.10 sürümünden itibaren çift tırnaklı etiketlerde kaçışlanması gereken tek karakter çift tırnağın kendisidir.

TAG alanı: hash ile JSON farkı

Belgelerin özellikle "sık karışıklık kaynağı" diye işaretlediği bir davranış var. Hash belgelerinde TAG alanının varsayılan ayırıcısı virgüldür; "Electronics,Gaming,PC" değeri üç ayrı etikete bölünür ve @category:{Gaming} belgeyi bulur. JSON belgelerinde ise varsayılan ayırıcı yoktur; aynı dizgi tek bir etiket olur ve Gaming araması belgeyi bulmaz, ancak dizginin tamamıyla yapılan arama bulur. JSON'da hash davranışını istiyorsanız alan tanımına açıkça SEPARATOR "," eklemeniz gerekir. Belgenin önerdiği yol ise değeri virgüllü dizgi yerine JSON dizisi olarak saklamak ve dizinin elemanlarını [*] ile indekslemektir:

# Hash: virgul varsayilan ayirici, uc ayri etiket olusur
HSET product:1 category "Electronics,Gaming,PC"
FT.CREATE products ON HASH PREFIX 1 product: SCHEMA category TAG

# JSON icin onerilen yol: dizi + [*]
JSON.SET product:1 $ '{"category": ["Electronics", "Gaming", "PC"]}'
FT.CREATE products ON JSON PREFIX 1 product: SCHEMA $.category[*] AS category TAG

Belge diziyi şu durumlarda önerir: veri yapısını siz denetliyorsanız, içinde boşluk veya noktalama bulunan değerler saklayacaksanız ve temiz, yapılandırılmış veri istiyorsanız. Hash'ten JSON'a geçiş yapıyorsanız veya veri size zaten ayraçlı dizgi olarak geliyorsa SEPARATOR kullanmak daha pratik olabilir.

FT.SEARCH sorgu sözdizimi

Sorgu dizgisi birden fazla kelime içeriyorsa tırnak içine alınmalıdır. Her alan türünün kendi yazımı vardır ve en sık yapılan hata, bir türün yazımını diğerinde kullanmaktır. Aşağıdaki tablo, sorgu belgelerinde geçen bisiklet örnek veri kümesindeki (description TEXT, condition TAG, price NUMERIC) temel kalıpları özetler:

Tam eşleşme ve aralık sorguları

Sayısal bir alanda tam eşleşme için başlangıcı ve bitişi aynı olan bir aralık yazarsınız. Aynı sonucu FILTER argümanıyla da alabilirsiniz; belge iki yolun anlamca eşdeğer olduğunu, ancak sorgu planının farklı olduğunu vurgular: FILTER, sorgu dizgisi (örneğin tüm belgeleri seçen *) değerlendirildikten sonra uygulanır. Belgedeki çıktılar uzun JSON içerdiği için kısaltılmıştır:

> FT.SEARCH idx:bicycle "@price:[270 270]"
1) (integer) 1
2) "bicycle:0"
3) 1) "$"
   2) "{\"pickup_zone\":\"POLYGON((-74.0610 40.7578, ...

> FT.SEARCH idx:bicycle "*" FILTER price 270 270
1) (integer) 1
2) "bicycle:0"
3) 1) "$"
   2) "{\"pickup_zone\":\"POLYGON((-74.0610 40.7578, ...

Aralık uçları varsayılan olarak dahildir; bir ucu dışarıda bırakmak için önüne ( koyarsınız. -inf, inf ve +inf açık aralık yazmanızı sağlar. Belgedeki örnekte @price:[500 1000] üç bisiklet döndürürken @price:[(1000 +inf] fiyatı 1000'den büyük beş bisikleti döndürür. Kısa metinler için belge tam metin yerine TAG kullanmayı önerir; etiket alanları hem indekste daha az yer kaplar hem de tam eşleşme sorgularını daha basit hale getirir.

Tam metin arama: kelime, önek, bulanık arama

Alan belirtmeden yazdığınız bir kelime tüm TEXT alanlarında aranır; @alan: ile aramayı tek alana daraltırsınız. Dildeki çok sık kelimeler (durdurma kelimeleri) indekslenmez ve bunlarla arama sonuç döndürmez; ayrıca tam ifade araması durdurma kelimesiyle başlayamaz. Önek araması ka* biçimindedir ve önek en az iki karakter olmalıdır. Sonek için *bikes, içerik için *infix* yazılır; bu sorguları hızlandırmak istediğiniz alanlarda WITHSUFFIXTRIE kullanabilirsiniz.

Bulanık arama, terimi % çiftleri arasına alarak yapılır: bir çift Levenshtein mesafesi 1, iki çift 2, üç çift (en yüksek değer) 3 anlamına gelir. Belgedeki örnekte yanlış yazılmış %optamized% sorgusu "optimized" kelimesini bulur. Bulanık aramayı belirli bir alanda yapacaksanız @description:(%optamized%) biçimini kullanın ve terimi tırnağa almayın; tırnak içine alınan terim tam eşleşme aramasına dönüşür ve % işaretleri düz karakter olarak değerlendirilir. Bir sınır daha: Search yalnızca Unicode temel çok dilli düzlemindeki karakterleri destekler, bu yüzden emoji gibi U+FFFF ötesindeki karakterler önek, sonek ve bulanık sorgularda bulunmaz. Türkçe harfler bu düzlemin içindedir.

FT.SEARCH idx:bicycle "@description: kids"
FT.SEARCH idx:bicycle "@model: ka*"
FT.SEARCH idx:bicycle "@brand:*bikes"
FT.SEARCH idx:bicycle "@description:(%%optamised%%)"

VE, VEYA, DEĞİL ve sorgu diyalekti

İki ifade arasındaki boşluk kesişim (VE), dikey çizgi birleşim (VEYA), ifadenin önündeki eksi işareti ise olumsuzlama (DEĞİL) anlamına gelir. Aynı alanda birden çok değer için kısa yazımlar vardır: metin alanında @description:(kids | small), etiket alanında @condition:{new | used}. Operatörlerin önceliği diyalekte göre değişir. Belge varsayılan diyalektin 1 olduğunu, 2. diyalektte VE'nin VEYA'dan önce geldiğini (expr1 expr2 | expr3 expr4 ifadesi (expr1 expr2) | (expr3 expr4) demektir) ve 1. diyalektin farklı davrandığını belirtir; bu yüzden parantez kullanmanızı önerir.

FT.SEARCH idx:bicycle "@price:[500 1000] @condition:{new}"
FT.SEARCH idx:bicycle "kids (@price:[500 1000] @condition:{used})"
FT.SEARCH idx:bicycle "@description:(kids | small) @condition:{new | used}"
FT.SEARCH idx:bicycle "@price:[500 1000] -@condition:{new}"

Uygulamadan gelen değerleri sorgu dizgisine metin birleştirerek yerleştirmek yerine PARAMS kullanabilirsiniz: sorguda $ad yazar, değeri PARAMS ile ayrıca verirsiniz. Bu özellik 2. veya daha yüksek diyalekt gerektirir ve alan adları gibi somut değer beklenmeyen yerlerde parametre kullanılamaz.

Sonuç sayısı, sayfalama ve sıralama

FT.SEARCH varsayılan olarak yalnızca ilk 10 sonucu döndürür (LIMIT 0 10). Yanıtın başındaki sayı ise döndürülen değil, eşleşen belge sayısıdır; bu yüzden 42 belge eşleşirse sayı 42 olur ama yalnızca 10 belge gelir. Yalnızca toplamı öğrenmek için LIMIT 0 0 kullanırsınız. Komut sayfasındaki örnek bunu gösterir:

> FT.SEARCH idx "@title:redis" NOCONTENT
 1) (integer) 42
 2) "doc:1"
 3) "doc:2"
...
11) "doc:10"

> FT.SEARCH idx "@title:redis" LIMIT 0 0
1) (integer) 42

NOCONTENT belge içeriği yerine yalnızca anahtar adlarını döndürür; Search'ü dışarıdaki bir belge koleksiyonunun indeksi gibi kullanıyorsanız işe yarar. RETURN ile yalnızca istediğiniz öznitelikleri alırsınız. Sayfalamada dikkat edilmesi gereken nokta şudur: LIMIT sıralama olmadan kullanılırsa sonuç sırası belirlenimli değildir ve ardışık sayfalarda yinelenen ya da eksik kayıtlar görebilirsiniz. Belge, kararlı sayfalama için benzersiz bir alanla SORTBY eklemeyi veya FT.AGGREGATE ile imleç (WITHCURSOR) kullanmayı önerir. Örneğin FT.SEARCH idx:bicycle "@price:[-inf 2000]" SORTBY price LIMIT 0 5 sorgusu belgedeki veride toplam 7 eşleşme bildirir ve en ucuz beş bisikleti fiyat sırasıyla döndürür.

FT.AGGREGATE ile gruplama ve hesaplama

Sorgu belgesi iki komutun işini net biçimde ayırır: yalnızca seçim (belirli koşulu sağlayan belgeler) ve izdüşüm (belirli alanlar) gerekiyorsa FT.SEARCH, eşleme fonksiyonu uygulamak, gruplamak veya özetlemek gerekiyorsa FT.AGGREGATE kullanılır. Belgedeki SQL karşılaştırması şöyledir:

Bir toplama hattı adımlardan oluşur. LOAD, alanları hatta yükler (__key yerleşik bir alandır). APPLY bir ifadeyi hesaplayıp yeni bir alan olarak ekler. GROUPBY bir veya daha fazla alana göre gruplar, REDUCE her gruba SUM, COUNT, AVG veya TOLIST gibi bir fonksiyon uygular. Aşağıdaki örnekte @price<1000 ifadesi fiyatı 1000'in altındaki bisiklete 1, diğerlerine 0 değerini verir ve sonuç durum bazında uygun fiyatlı bisiklet sayısıdır:

> FT.AGGREGATE idx:bicycle "*" LOAD 1 price APPLY "@price<1000" AS price_category GROUPBY 1 @condition REDUCE SUM 1 "@price_category" AS "num_affordable"
1) "3"
2) 1) "condition"
   1) "refurbished"
   2) "num_affordable"
   3) "1"
3) 1) "condition"
   1) "used"
   2) "num_affordable"
   3) "1"
4) 1) "condition"
   1) "new"
   2) "num_affordable"
   3) "3"

Toplama fonksiyonları GROUPBY dışında kullanılamaz. Tüm belgeler üzerinde tek bir toplam istiyorsanız belgenin önerdiği hile, APPLY ile herkese aynı sabit değeri verip ona göre gruplamaktır: APPLY "'bicycle'" AS type GROUPBY 1 @type REDUCE COUNT 0 AS num_total sorgusu belgedeki veride num_total için 10 döndürür. Birden çok REDUCE aynı grupta kullanılabilir, gruplamalar zincirlenebilir. Vektör arama sorguları ise toplama sorgularıyla birleştirilemez.

Sık yapılan hatalar

• Sorguda JSONPath kullanmak: FT.SEARCH içinde $.name yerine şemada verdiğiniz öznitelik adını (@name) yazın.
• JSON'da virgüllü etiket: Ayırıcı belirtmediyseniz "black,silver" tek etikettir. Dizi ve [*] kullanın ya da SEPARATOR "," ekleyin.
• Etiket sorgusunda süslü parantezi unutmak: TAG alanı @alan:{deger} biçiminde sorgulanır; süslü parantez zorunludur.
• 10'dan fazla sonuç beklemek: Varsayılan LIMIT 0 10'dur; toplam sayı ile dönen kayıt sayısını karıştırmayın.
• Sıralamasız sayfalama: LIMIT tek başına kararlı sayfa vermez; SORTBY ekleyin.
• Her alanı SORTABLE yapmak: Bellek maliyeti vardır; yalnızca gerçekten sıraladığınız alanlarda kullanın. Belleği ölçmek için bellek kullanımı yazısına bakın.
• İndeksi silerken veriyi de silmek sanmak: FT.DROPINDEX varsayılan olarak belgeleri silmez, yalnızca DD bayrağıyla siler. TEMPORARY ile oluşturulan geçici indeksler ise süresi dolduğunda ilişkili kayıtları da düşürür.
• Cluster'da belgeleri dağıtmak: Komut sayfası, cluster'daki bir indeksin belgelerinin indeksle aynı shard'da olması gerektiğini ve bunun için anahtarlara indeks adıyla etiket (doc:1{idx}) verilebileceğini belirtir. Hash etiketleri için cluster ve hash slot yazısına bakın.

Bir de yetki konusu var: FT.SEARCH yalnızca kullanıcının okuma yetkisi olan anahtarları döndürür. Bir ACL kullanıcısı beklediğinizden az sonuç görüyorsa önce anahtar desenlerine bakın; ayrıntılar ACL yazısında.

Sık Sorulan Sorular

Redis Search için ayrı modül kurmam gerekir mi?

Redis 8.0 ve sonrasında hayır; sürüm notlarına göre Redis 8, Redis Stack ile eski Community Edition'ı tek bir Redis Open Source dağıtımında birleştirdi ve Search bu dağıtımın parçası. Daha eski bir sunucu kullanıyorsanız FT.* komutları ancak modül yüklüyse çalışır.

Var olan verilerim indekse girer mi?

Evet. İndeks oluşturulduğunda önekle eşleşen mevcut belgeler arka planda indekslenir; büyük veri kümelerinde bu biraz sürebilir. Bu ilk taramayı istemiyorsanız SKIPINITIALSCAN seçeneği vardır. Sonradan yazılan belgeler yazma anında indekslenir.

Türkçe metinlerde kök bulma çalışır mı?

FT.CREATE sayfasının desteklenen diller listesinde turkish yer alır. İndeksi LANGUAGE turkish ile oluşturursanız indeksleme sırasında bu dilin kök bulucusu kullanılır; indeks oluştururken dil verdiyseniz sorgularda ayrıca belirtmeniz gerekmez.

TAG mı TEXT mi kullanmalıyım?

Değeri parçalayıp kelime kelime aramak istiyorsanız TEXT, değeri bütün olarak eşleştirmek istiyorsanız (durum, kategori, e-posta, ülke kodu) TAG kullanın. Belge kısa metinlerde TAG'i daha az yer kapladığı ve tam eşleşme sorgularını basitleştirdiği için önerir. Aynı alanı iki türde birden indekslemek de mümkündür.

Arama sonuçlarını istemci tarafında önbelleğe alabilir miyim?

Redis'in sunucu destekli istemci önbelleği FT.* komutlarını önbelleğe almaz; belge bunu açıkça istisna olarak sayar. Ayrıntılar için client-side caching yazısına bakabilirsiniz.

Marka adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen kuruluşlarla bayilik veya ortaklık ilişkisi bulunduğu anlamına gelmez.

İlgili içerikler: Redis öğrenme rehberi · Redis JSON komutları · Hash komutları · Redis GEO komutları · Bloom ve Cuckoo filter · Redis Cluster ve hash slot