feat: Elastic Search (search-files) API Endpoint

docs/api_reference/file.rst

@@ -10,6 +10,7 @@ nisystemlink.clients.file
    .. automethod:: api_info
    .. automethod:: get_files
    .. automethod:: query_files_linq
+   .. automethod:: search_files
    .. automethod:: delete_file
    .. automethod:: delete_files
    .. automethod:: upload_file

docs/getting_started.rst

@@ -252,7 +252,7 @@ default connection. The default connection depends on your environment.
 
 With a :class:`.FileClient` object, you can:
 
-* Get the list of files, download and delete files
+* Get the list of files, query and search for files, download and delete files
 
 Examples
 ~~~~~~~~
@@ -266,6 +266,14 @@ Get the metadata of a File using its Id and download it.
 Upload a File from disk or memory to SystemLink
 
 .. literalinclude:: ../examples/file/upload_file.py
+   :language: python
+   :linenos:
+
+Search for files with filtering and pagination
+
+.. literalinclude:: ../examples/file/search_files.py
+   :language: python
+   :linenos:
 
 Feeds API
 -------

examples/file/search_files.py

@@ -0,0 +1,128 @@
+"""Example demonstrating how to search for files using the File API."""
+
+import io
+import time
+
+from nisystemlink.clients.core import HttpConfiguration
+from nisystemlink.clients.file import FileClient, models
+from nisystemlink.clients.file.models import SearchFilesOrderBy, UpdateMetadataRequest
+
+# Configure connection to SystemLink server
+server_configuration = HttpConfiguration(
+    server_uri="https://yourserver.yourcompany.com",
+    api_key="YourAPIKeyGeneratedFromSystemLink",
+)
+
+client = FileClient(configuration=server_configuration)
+
+# Upload a test file first
+print("Uploading test file...")
+test_file_content = b"This is a test file for search demonstration."
+test_file = io.BytesIO(test_file_content)
+test_file.name = "search-example-test-file.txt"
+
+file_id = client.upload_file(file=test_file)
+print(f"Uploaded test file with ID: {file_id}")
+
+# Wait for the file to be indexed for search
+# Note: Files may take a few seconds to appear in search results after upload
+time.sleep(5)
+print()
+
+# Example 1: Basic file search with filter - search for the uploaded file
+print("Example 1: Search for the uploaded test file")
+search_request = models.SearchFilesRequest(
+    filter='name:("search-example-test-file.txt")',
+    skip=0,
+    take=10,
+)
+
+response = client.search_files(search_request)
+print(
+    f"Found {response.total_count.value if response.total_count else 0} file(s) matching the filter"
+)
+if response.available_files:
+    for file in response.available_files:
+        if file.properties:
+            print(
+                f"- {file.properties.get('Name')} (ID: {file.id}, Size: {file.size} bytes)"
+            )
+
+# Example 2: Search with wildcard pattern
+print("\nExample 2: Search with wildcard pattern")
+search_request = models.SearchFilesRequest(
+    filter='name:("search-example*")',
+    skip=0,
+    take=20,
+    order_by=SearchFilesOrderBy.CREATED,
+    order_by_descending=True,
+)
+
+response = client.search_files(search_request)
+print(
+    f"Found {response.total_count.value if response.total_count else 0} file(s) starting with 'search-example'"
+)
+if response.available_files:
+    for file in response.available_files:
+        if file.properties:
+            print(
+                f"- {file.properties.get('Name')} created at {file.created} (Size: {file.size} bytes)"
+            )
+
+# Example 3: Search by size range
+print("\nExample 3: Search by size range")
+search_request = models.SearchFilesRequest(
+    filter="size:([1 TO 1000])",
+    skip=0,
+    take=10,
+)
+
+response = client.search_files(search_request)
+print(
+    f"Found {response.total_count.value if response.total_count else 0} file(s) between 1 and 1000 bytes"
+)
+if response.available_files:
+    for file in response.available_files:
+        if file.properties:
+            print(f"- {file.properties.get('Name')} (Size: {file.size} bytes)")
+
+# Example 4: Search by multiple custom properties
+print("\nExample 4: Search by multiple custom properties")
+print("Adding custom properties to existing file...")
+
+# Update the existing file with custom properties
+custom_metadata = UpdateMetadataRequest(
+    replace_existing=False,
+    properties={
+        "TestProperty1": "TestValue1",
+        "TestProperty2": "TestValue2",
+    },
+)
+client.update_metadata(metadata=custom_metadata, id=file_id)
+
+# Wait for indexing
+time.sleep(5)
+
+# Search by multiple custom properties using AND operator
+search_request = models.SearchFilesRequest(
+    filter='(properties.TestProperty1:"TestValue1") AND (properties.TestProperty2:"TestValue2")',
+    skip=0,
+    take=10,
+)
+
+response = client.search_files(search_request)
+print(
+    f"Found {response.total_count.value if response.total_count else 0} file(s) with "
+    "TestProperty1=TestValue1 AND TestProperty2=TestValue2"
+)
+if response.available_files:
+    for file in response.available_files:
+        if file.properties:
+            print(f"- {file.properties.get('Name')}")
+            print(f"  TestProperty1: {file.properties.get('TestProperty1')}")
+            print(f"  TestProperty2: {file.properties.get('TestProperty2')}")
+
+# Clean up: delete the test file
+print("\nCleaning up...")
+client.delete_file(id=file_id)
+print(f"Deleted test file with ID: {file_id}")

nisystemlink/clients/file/_file_client.py

@@ -163,6 +163,29 @@ def query_files_linq(
         """
         ...
 
+    @post("service-groups/Default/search-files")
+    def search_files(
+        self, request: models.SearchFilesRequest
+    ) -> models.SearchFilesResponse:
+        """Search for files based on filter criteria.
+
+        Note:
+            This endpoint requires Elasticsearch to be available in the SystemLink cluster.
+            If Elasticsearch is not configured, this method will fail with an ApiException.
+            For deployments without Elasticsearch, use `query_files_linq()` instead.
+
+        Args:
+            request: The search request containing filter, pagination, and sorting parameters.
+
+        Returns:
+            SearchFilesResponse: Response containing matching files and total count.
+
+        Raises:
+            ApiException: if unable to communicate with the File Service or if Elasticsearch
+                is not available in the cluster.
+        """
+        ...
+
     @params({"force": True})  # type: ignore
     @delete("service-groups/Default/files/{id}", args=[Path])
     def delete_file(self, id: str) -> None:

nisystemlink/clients/file/models/__init__.py

@@ -1,9 +1,17 @@
 from ._file_metadata import FileMetadata
-from ._file_query_order_by import FileQueryOrderBy, FileLinqQueryOrderBy
+from ._file_query_order_by import (
+    FileQueryOrderBy,
+    FileLinqQueryOrderBy,
+    SearchFilesOrderBy,
+)
 from ._file_query_response import FileQueryResponse
 from ._link import Link
 from ._operations import V1Operations
 from ._update_metadata import UpdateMetadataRequest
 from ._file_linq_query import FileLinqQueryRequest, FileLinqQueryResponse
+from ._search_files_request import SearchFilesRequest
+from ._search_files_response import SearchFilesResponse
+from ._base_file_response import BaseFileResponse, TotalCount, TotalCountRelation
+from ._base_file_request import BaseFileRequest
 
 # flake8: noqa

nisystemlink/clients/file/models/_base_file_request.py

@@ -0,0 +1,25 @@
+from nisystemlink.clients.core._uplink._json_model import JsonModel
+
+
+class BaseFileRequest(JsonModel):
+    """Base class for file request models containing common query parameters."""
+
+    filter: str | None = None
+    """
+    Filter string for searching/querying files.
+    """
+
+    skip: int | None = None
+    """
+    How many files to skip in the result when paging.
+    """
+
+    take: int | None = None
+    """
+    How many files to return in the result.
+    """
+
+    order_by_descending: bool | None = False
+    """
+    Whether to sort in descending order.
+    """

nisystemlink/clients/file/models/_base_file_response.py

@@ -0,0 +1,39 @@
+from enum import Enum
+from typing import List
+
+from nisystemlink.clients.core._uplink._json_model import JsonModel
+
+from ._file_metadata import LinqQueryFileMetadata
+
+
+class TotalCountRelation(str, Enum):
+    """Describes the relation the returned total count value has with respect to the total number of files."""
+
+    EQUALS = "eq"
+    """Equals, meaning that the returned items are all the items that matched the filter."""
+
+    GREATER_THAN_OR_EQUAL = "gte"
+    """Greater or equal, meaning that the take limit has been hit, but there are further items that match the query."""
+
+
+class TotalCount(JsonModel):
+    """The total number of files that match the query regardless of skip and take values"""
+
+    relation: TotalCountRelation
+    """
+    Describes the relation the returned total count value has with respect to the total number of
+    files matched by the query.
+    """
+
+    value: int
+    """Describes the number of files that were returned as a result of the query in the database"""
+
+
+class BaseFileResponse(JsonModel):
+    """Base class for file response models containing a list of files and total count."""
+
+    available_files: List[LinqQueryFileMetadata]
+    """The list of files returned by the query"""
+
+    total_count: TotalCount
+    """The total number of files that match the query regardless of skip and take values"""

nisystemlink/clients/file/models/_file_linq_query.py

@@ -1,53 +1,18 @@
-from typing import List
-
-from nisystemlink.clients.core._uplink._json_model import JsonModel
-from nisystemlink.clients.file.models._file_metadata import LinqQueryFileMetadata
+from nisystemlink.clients.file.models._base_file_request import BaseFileRequest
+from nisystemlink.clients.file.models._base_file_response import BaseFileResponse
 from nisystemlink.clients.file.models._file_query_order_by import FileLinqQueryOrderBy
 
 
-class FileLinqQueryRequest(JsonModel):
-    filter: str | None = None
-    """
-    The filter criteria for files. Consists of a string of queries composed using AND/OR operators.
-    String values and date strings need to be enclosed in double quotes. Parentheses can be used
-    around filters to better define the order of operations.
-
-    Example Filter syntax: '[property name][operator][operand] and [property name][operator][operand]'
-    """
+class FileLinqQueryRequest(BaseFileRequest):
+    """Request model for LINQ query operations."""
 
     order_by: FileLinqQueryOrderBy | None = None
-    """The property by which to order the files in the response."""
-
-    order_by_descending: bool | None = False
-    """If true, the files are ordered in descending order based on the property specified in `order_by`."""
-
-    take: int | None = None
-    """The maximum number of files to return in the response. Default value is 1000"""
-
-
-class TotalCount(JsonModel):
-    """The total number of files that match the query regardless of skip and take values"""
-
-    relation: str
     """
-    Describes the relation the returned total count value has with respect to the total number of
-    files matched by the query.
-
-    Possible values:
-
-    - "eq" -> equals, meaning that the returned items are all the items that matched the filter.
-
-    - "gte" -> greater or equal, meaning that there the take limit has been hit, but there are further
-    items that match the query in the database.
+    The property by which to order the files in the response.
     """
 
-    value: int
-    """Describes the number of files that were returned as a result of the query in the database"""
-
 
-class FileLinqQueryResponse(JsonModel):
-    available_files: List[LinqQueryFileMetadata]
-    """The list of files returned by the query"""
+class FileLinqQueryResponse(BaseFileResponse):
+    """Response model for LINQ query operations."""
 
-    total_count: TotalCount
-    """The total number of files that match the query regardless of skip and take values"""
+    pass

nisystemlink/clients/file/models/_file_query_order_by.py

@@ -10,9 +10,21 @@ class FileQueryOrderBy(Enum):
     LAST_UPDATED_TIMESTAMP = "lastUpdatedTimestamp"
 
 
-class FileLinqQueryOrderBy(Enum):
+class FileLinqQueryOrderBy(str, Enum):
     """Order Files LINQ Query by Metadata for POST /query-files-linq endpoint."""
 
+    NAME = "name"
+    CREATED = "created"
+    UPDATED = "updated"
+    EXTENSION = "extension"
+    SIZE = "size"
+    WORKSPACE = "workspace"
+
+
+class SearchFilesOrderBy(str, Enum):
+    """Order Files Search by Metadata for POST /search-files endpoint."""
+
+    NAME = "name"
     CREATED = "created"
     UPDATED = "updated"
     EXTENSION = "extension"

nisystemlink/clients/file/models/_search_files_request.py

@@ -0,0 +1,11 @@
+from nisystemlink.clients.file.models._base_file_request import BaseFileRequest
+from nisystemlink.clients.file.models._file_query_order_by import SearchFilesOrderBy
+
+
+class SearchFilesRequest(BaseFileRequest):
+    """Request model for searching files."""
+
+    order_by: SearchFilesOrderBy | None = None
+    """
+    The property by which to order the files in the response.
+    """

nisystemlink/clients/file/models/_search_files_response.py

@@ -0,0 +1,7 @@
+from ._base_file_response import BaseFileResponse
+
+
+class SearchFilesResponse(BaseFileResponse):
+    """Response model for search files operation."""
+
+    pass