From 4c2be48070f105d6f3fcdfe36b4ae24a1ba3f7e8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jens=20Pryce-=C3=85klundh?=
 <112686610+JPryce-Aklundh@users.noreply.github.com>
Date: Tue, 20 Aug 2024 08:25:35 +0200
Subject: [PATCH] clarify text index use

---
 modules/ROOT/pages/query-tuning/indexes.adoc | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/modules/ROOT/pages/query-tuning/indexes.adoc b/modules/ROOT/pages/query-tuning/indexes.adoc
index a32db2c53..42136fe17 100644
--- a/modules/ROOT/pages/query-tuning/indexes.adoc
+++ b/modules/ROOT/pages/query-tuning/indexes.adoc
@@ -84,6 +84,26 @@ In summary, `TEXT` indexes support the following predicates:
 
 |===
 
+=== Ensuring text index use
+
+In order for the planner to use text indexes, it must be able to confirm that the properties included in the predicate are `STRING` values.
+This is not possible when accessing property values within nodes or relationships, or values within a `MAP`, since Cypher does not store the type information of these values.
+To ensure text indexes are used in these cases, the xref:functions/string.adoc#functions-tostring[`toString`] function should be used.
+
+.Text index not used
+[source,cypher]
+----
+WITH {name: 'John'} AS varName
+MERGE (:Person {name:varName.name})
+----
+
+.Text index used
+[source,cypher]
+----
+WITH {name: 'John'} AS varName
+MERGE (:Person {name: toString(varName.name)})
+----
+
 == Index preference
 
 When multiple indexes are available and able to solve a predicate, there is an order defined that decides which index to use.