Search Files

The search-files report search through the available files in an ownCloud user’s filesystem, based on a rudimentary filename pattern match.

By default, the report uses ownCloud’s default search provider to power the search functionality. However, other search providers, such as search_elastic and search_lucene greatly enrich the ability to search, such as being able to search through file content, as well as by a file’s name. When installed, they replace ownCloud’s default search provider and the search API will automatically use them.

When using the default search provider, if you use the search string "ownCloud", files whose filename has "ownCloud" in it will be matched. However, if installed the search_elastic app, the report also retrieves files that have "ownCloud" in the file’s contents.

Core Details

Request Path Method Content Type

remote.php/dav/files/<user>

REPORT

text/xml

The Request

An authenticated REPORT request needs to be made to search for all files stored in a user’s ownCloud filesystem

Example Request

curl --silent \
  -X REPORT \
  --data "@supported.xml" \
  -u admin:admin \
  'http://localhost/remote.php/dav/files/admin' | xmllint --format -

The request must include a request body that includes the search pattern, and can also include a list of properties to return.

Example Request Bodies

Below, are several examples of XML response bodies.

Searching For Records

In the search element, specify the search pattern to filter the list of files to return.

<?xml version="1.0" encoding="UTF-8"?>
<oc:search-files
    xmlns:a="DAV:"
    xmlns:oc="http://owncloud.org/ns">
    <oc:search>
        <oc:pattern>web</oc:pattern>
    </oc:search>
</oc:search-files>

Filtering Records

The filter-rules element provides the ability to filter records based on a range of properties. In the example below, you can see how to filter out any file that has not been favorited.

<?xml version="1.0" encoding="UTF-8"?>
<oc:search-files
    xmlns:a="DAV:"
    xmlns:oc="http://owncloud.org/ns">
    <oc:search>
        <oc:pattern>web</oc:pattern>
    </oc:search>
</oc:search-files>

Limiting The Number Of Results Returned

To limit the number of results returned, use a combination of the search element’s limit, and offset elements, as in the following example. In the example below, at most one hundred records, starting from record 200, will be returned.

<?xml version="1.0" encoding="UTF-8"?>
<oc:search-files
    xmlns:a="DAV:"
    xmlns:oc="http://owncloud.org/ns">
    <oc:search>
        <!-- The number of results to retrieve -->
        <oc:limit>100</oc:limit>
        <!-- The offset to retrieve (here, 200 would be indicate the second page) -->
        <oc:offset>200</oc:offset>
    </oc:search>
</oc:search-files>

Reducing The File Properties Returned

However, if a specific list of properties is required for each file, then a prop element needs to be included in the response body, such as in the example below.

Table 1. Available File Properties
Property Description Namespace

getcontentlength

The file’s content length. This is only sent for files, not for folders and collections. Refer to the size property for folders and collections.

DAV

getcontenttype

The file’s content type.

DAV

getetag

The file’s ETag

DAV

getlastmodified

The last modified date of the file

DAV

lockdiscovery

Supports the "persistent file locking" backend feature. For more information on this property, please refer to the W3C spec.

DAV

resourcetype

The resource’s type. If the resource is a folder, then the value is set to collection, otherwise, no value is returned.

DAV

comments-unread

The number of comments on the item that have yet to be read.

http://owncloud.org/ns

favorite

Indicates whether the file has been favorited or not

http://owncloud.org/ns

fileid

The id of the file

http://owncloud.org/ns

owner-display-name

The display name of the file owner

http://owncloud.org/ns

owner-id

The id of the file owner

http://owncloud.org/ns

permissions

The permissions set on the file

http://owncloud.org/ns

share-types

It is an OC-specific property which summarizes what outgoing share types are applied to the current item. The share type values are:

  • 0: user share

  • 1: group share

  • 3: link shares

http://owncloud.org/ns

size

The size of a folder or collection. This property is not returned for files. Refer to the getcontentlength property for folders and collections.

http://owncloud.org/ns

tags

A collection of tags that have been added to the file.

http://owncloud.org/ns

<?xml version="1.0" encoding="UTF-8"?>
<oc:search-files
    xmlns:a="DAV:"
    xmlns:oc="http://owncloud.org/ns">
    <a:prop>
        <a:getcontentlength />
        <a:getcontenttype />
        <a:getetag />
        <a:getlastmodified />
        <a:lockdiscovery />
        <a:resourcetype />
        <oc:comments-unread />
        <oc:favorites />
        <oc:fileid />
        <oc:owner-display-name />
        <oc:permissions />
        <oc:share-types />
        <oc:size />
        <oc:tags />
    </a:prop>
    <oc:search>
        <oc:pattern>site</oc:pattern>
    </oc:search>
</oc:search-files>
The example uses xmllint to make the response more readable. Xmllint is available in the libxml2 package.

The Response

Success

Successful requests return two things:

  1. An XML payload.

  2. A status of HTTP/1.1 207 Multi-Status.

You can see an example of the XML payload below. The XML payload contains a response element for each file. And each response element contains three items:

  1. A link to the file (href).

  2. The requested properties, along with their respective values (propstat).

  3. The file’s status (status).

Search Response
<?xml version="1.0"?>
<d:multistatus
    xmlns:d="DAV:"
    xmlns:s="http://sabredav.org/ns"
    xmlns:oc="http://owncloud.org/ns">
  <d:response>
    <d:href>/remote.php/dav/files/admin/Test/Sub-test/Site-Plan.md</d:href>
    <d:propstat>
      <d:prop>
        <oc:id>00000065oc21s4c9iej2</oc:id>
        <oc:downloadURL/>
        <oc:fileid>65</oc:fileid>
        <oc:permissions>RDNVW</oc:permissions>
        <oc:size>423</oc:size>
        <oc:owner-id>admin</oc:owner-id>
        <oc:owner-display-name>admin</oc:owner-display-name>
        <d:getlastmodified>Fri, 28 Jul 2017 05:51:07 GMT</d:getlastmodified>
        <d:getetag>"0286fcdabf5b4f5ef84788d86c37e245"</d:getetag>
        <d:getcontenttype>text/markdown</d:getcontenttype>
      </d:prop>
      <d:status>HTTP/1.1 200 OK</d:status>
    </d:propstat>
  </d:response>
</d:multistatus>

Failure

If The Payload File Cannot Be Read Or Is Invalid XML

If the payload file cannot be read or is invalid XML, then the following XML response is sent, along with an HTTP/1.1 500 Internal Server Error status code.

<?xml version="1.0" encoding="utf-8"?>
<d:error
    xmlns:d="DAV:"
    xmlns:s="http://sabredav.org/ns">
  <s:exception>Sabre\Xml\ParseException</s:exception>
  <s:message>This should never happen (famous last words)</s:message>
</d:error>

If a Non-Existent Property Is Requested

If a non-existent property is requested, then an additional propstat element is returned, as in the example below, which contains a list of the properties which were not available.

  <d:status>HTTP/1.1 200 OK</d:status>
</d:propstat>
<d:propstat>
  <d:prop>
    <oc:downloadUR/>
  </d:prop>
  <d:status>HTTP/1.1 404 Not Found</d:status>