From 9ebb183ffd1b99eaa18fa0ef156289ff651bee17 Mon Sep 17 00:00:00 2001
From: Salih Candir <salih@live.at>
Date: Wed, 12 Jul 2023 18:21:05 +0200
Subject: [PATCH] Added support for `format` parameter to specify the sql
 response format (#161)

* feat: add test for SQL query endpoint

Signed-off-by: Salih Candir <salih@live.at>

* format on Sql

cherry-pick from @archipelweb see: https://github.com/opensearch-project/opensearch-php/pull/156

Signed-off-by: archipelweb <github@archipel-web.com>

* docs: add 'format' to allowed SQL query params

Signed-off-by: Salih Candir <salih@live.at>

* docs: update changelog

Signed-off-by: Salih Candir <salih@live.at>

* feat: make failed message of testFormatParamIsAllowedToSet more precise

Signed-off-by: Salih Candir <salih@live.at>

* refactor: add an line break at the end of line

Signed-off-by: Salih Candir <salih@live.at>

* docs: add example how to use query using sql

Signed-off-by: Salih Candir <salih@live.at>

---------

Signed-off-by: Salih Candir <salih@live.at>
Signed-off-by: archipelweb <github@archipel-web.com>
Co-authored-by: archipelweb <github@archipel-web.com>
---
 CHANGELOG.md                               |  1 +
 USER_GUIDE.md                              | 11 +++
 src/OpenSearch/Endpoints/Sql/Query.php     |  2 +-
 src/OpenSearch/Namespaces/SqlNamespace.php |  1 +
 tests/Endpoints/SqlQueryEndpointTest.php   | 78 ++++++++++++++++++++++
 5 files changed, 92 insertions(+), 1 deletion(-)
 create mode 100644 tests/Endpoints/SqlQueryEndpointTest.php

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7f4743198..e60688b27 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - Added support for Amazon OpenSearch Serverless SigV4 signing ([#119](https://github.com/opensearch-project/opensearch-php/pull/119))
 - Added `includePortInHostHeader` option to `ClientBuilder::fromConfig` ([#118](https://github.com/opensearch-project/opensearch-php/pull/118))
 - Added the `RefreshSearchAnalyzers` endpoint ([[#152](https://github.com/opensearch-project/opensearch-php/issues/152)) 
+- Added support for `format` parameter to specify the sql response format ([#161](https://github.com/opensearch-project/opensearch-php/pull/161))
 
 ### Changed
 
diff --git a/USER_GUIDE.md b/USER_GUIDE.md
index 006ee5d73..4bdbfc993 100644
--- a/USER_GUIDE.md
+++ b/USER_GUIDE.md
@@ -213,6 +213,16 @@ class MyOpenSearchClass
         var_dump($docs['hits']['total']['value'] > 0);
     }
 
+    // Write queries in SQL
+    public function searchUsingSQL()
+    {
+        $docs = $this->client->sql()->query([
+          'query' => "SELECT * FROM INDEX_NAME WHERE name = 'wrecking'",
+          'format' => 'json'
+        ]);
+        var_dump($docs['hits']['total']['value'] > 0);
+    }
+
     public function getMultipleDocsByIDs()
     {
         $docs = $this->client->search([
@@ -338,6 +348,7 @@ try {
     $e->getOneByID();
     $e->getMultipleDocsByIDs();
     $e->search();
+    $e->searchUsingSQL();
     $e->searchByPointInTime();
     $e->deleteByQuery('');
     $e->deleteByID();
diff --git a/src/OpenSearch/Endpoints/Sql/Query.php b/src/OpenSearch/Endpoints/Sql/Query.php
index badbbe38c..1ba8170f9 100644
--- a/src/OpenSearch/Endpoints/Sql/Query.php
+++ b/src/OpenSearch/Endpoints/Sql/Query.php
@@ -19,7 +19,7 @@ class Query extends AbstractEndpoint
 {
     public function getParamWhitelist(): array
     {
-        return [];
+        return ['format'];
     }
 
     public function getURI(): string
diff --git a/src/OpenSearch/Namespaces/SqlNamespace.php b/src/OpenSearch/Namespaces/SqlNamespace.php
index ff5a1366d..8f747d2b1 100644
--- a/src/OpenSearch/Namespaces/SqlNamespace.php
+++ b/src/OpenSearch/Namespaces/SqlNamespace.php
@@ -20,6 +20,7 @@ class SqlNamespace extends AbstractNamespace
 {
     /**
      * $params['query'] = (string) The SQL Query
+     * $params['format'] = (string) The response format
      * $params['cursor'] = (string) The cursor given by the server
      * $params['fetch_size'] = (int) The fetch size
      *
diff --git a/tests/Endpoints/SqlQueryEndpointTest.php b/tests/Endpoints/SqlQueryEndpointTest.php
new file mode 100644
index 000000000..1a4c033c3
--- /dev/null
+++ b/tests/Endpoints/SqlQueryEndpointTest.php
@@ -0,0 +1,78 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * Copyright OpenSearch Contributors
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Elasticsearch PHP client
+ *
+ * @link      https://github.com/elastic/elasticsearch-php/
+ * @copyright Copyright (c) Elasticsearch B.V (https://www.elastic.co)
+ * @license   http://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0
+ * @license   https://www.gnu.org/licenses/lgpl-2.1.html GNU Lesser General Public License, Version 2.1
+ *
+ * Licensed to Elasticsearch B.V under one or more agreements.
+ * Elasticsearch B.V licenses this file to you under the Apache 2.0 License or
+ * the GNU Lesser General Public License, Version 2.1, at your option.
+ * See the LICENSE file in the project root for more information.
+ */
+
+namespace OpenSearch\Tests\Endpoints;
+
+use OpenSearch\Common\Exceptions\UnexpectedValueException;
+use OpenSearch\Endpoints\Sql\Query;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * @covers \OpenSearch\Endpoints\Sql\Query
+ */
+class SqlQueryEndpointTest extends TestCase
+{
+    /**
+     * @var Query
+     */
+    private $endpoint;
+
+    protected function setUp(): void
+    {
+        $this->endpoint = new Query();
+    }
+
+    public function testFormatIsInParamWhitelist(): void
+    {
+        $this->assertContains('format', $this->endpoint->getParamWhitelist());
+    }
+
+    public function testMethodIsPost(): void
+    {
+        $this->assertSame('POST', $this->endpoint->getMethod());
+    }
+
+    public function testUriIsSqlPlugin(): void
+    {
+        $this->assertSame('/_plugins/_sql', $this->endpoint->getURI());
+    }
+
+    public function testFormatParamIsAllowedToSet(): void
+    {
+        try {
+            $this->endpoint->setParams([
+                'format' => 'json',
+            ]);
+        } catch (UnexpectedValueException $e) {
+            $this->fail('The format param should be allowed to set but it was not. Format is may not whitelisted.');
+        }
+    }
+
+    public function testFormatParamIsJson(): void
+    {
+        $this->endpoint->setParams([
+            'format' => 'json',
+        ]);
+
+        $params = $this->endpoint->getParams();
+        $this->assertSame('json', $params['format']);
+    }
+}