From d7a99a9815e57648daa1e058235d379008a0d937 Mon Sep 17 00:00:00 2001
From: Clement Boirie <cboirie@beapi.fr>
Date: Mon, 24 Jun 2024 22:21:57 +0200
Subject: [PATCH] docs: add documentation for `WordPress.DB.SlowDBQuery`

---
 WordPress/Docs/DB/SlowDBQueryStandard.xml | 83 +++++++++++++++++++++++
 1 file changed, 83 insertions(+)
 create mode 100644 WordPress/Docs/DB/SlowDBQueryStandard.xml

diff --git a/WordPress/Docs/DB/SlowDBQueryStandard.xml b/WordPress/Docs/DB/SlowDBQueryStandard.xml
new file mode 100644
index 0000000000..93dbbb6b83
--- /dev/null
+++ b/WordPress/Docs/DB/SlowDBQueryStandard.xml
@@ -0,0 +1,83 @@
+<?xml version="1.0"?>
+<documentation xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:noNamespaceSchemaLocation="https://phpcsstandards.github.io/PHPCSDevTools/phpcsdocs.xsd"
+    title="Slow DB Query"
+    >
+    <standard>
+    <![CDATA[
+    For performance reason, it's recommended to avoid doing lots of meta queries.
+    The underlying SQL request generated by those queries can be extremely slow queries especially for complexe meta query.
+    ]]>
+    </standard>
+    <code_comparison>
+        <code title="Valid: Using tax_query to retrieve a list of posts">
+        <![CDATA[
+$query = new WP_Query(
+    array(
+        'tax_query' => array(
+            array(
+                'taxonomy' => 'color',
+                'field'    => 'slug',
+                'terms'    => array(
+                    'blue',
+                    'red',
+                )
+            )
+        )
+    )
+);
+        ]]>
+        </code>
+        <code title="Invalid: Using meta_query to retrieve a list of posts">
+        <![CDATA[
+$query = new WP_Query(
+    array(
+        'meta_query' => array(
+            array(
+                'key'     => 'color',
+                'compare' => 'IN',
+                'value'   => array(
+                    'blue',
+                    'red',
+                )
+            )
+        )
+    )
+);
+        ]]>
+        </code>
+    </code_comparison>
+    <code_comparison>
+        <code title="Valid: in case of binary metadata (true/false) check if meta_key exist and remove it otherwise">
+        <![CDATA[
+// mark post 123 as "featured"
+update_post_meta( 123, 'is_featured', true );
+
+// remove "featured" state for post 456
+delete_post_meta( 456, 'is_featured' );
+
+$query = new WP_Query(
+    array(
+        'meta_key' => 'is_featured'
+    ),
+);
+        ]]>
+        </code>
+        <code title="Invalid: check for the value of a binary metadata, which is slower">
+        <![CDATA[
+// mark post 123 as "featured"
+update_post_meta( 123, 'is_featured', true );
+
+// mark post 456 as not "featured"
+update_post_meta( 456, 'is_featured', false );
+
+$query = new WP_Query(
+    array(
+        'meta_key' => 'is_featured',
+        'meta_value' => true
+    ),
+);
+        ]]>
+        </code>
+    </code_comparison>
+</documentation>