Combine or Negate

Group or separate items in your search

You can add together multiple search parameters to expand your search. You can even combine negated search terms for more advanced tasks.

In annotation search, Filter and Rank is a list of Annotation objects. Filtered annotations will be ANDed.

info

Before using the Python SDK, Node.js SDK, or any of our gRPC clients, ensure they are properly installed on your machine. Refer to their respective installation guides for instructions on how to install and initialize them.

OR Search Operation

The OR filter lets you expand your search to include results that match any of the specified conditions, rather than requiring all of them to be met.

Python SDK
Node.js SDK

# Import necessary modules
from clarifai.client.search import Search
from clarifai.client.user import User
from google.protobuf import struct_pb2
from PIL import Image
import requests
from IPython.display import display

# User-specific credentials
USER_ID = ''  # User ID
APP_ID = ''   # Application ID
PAT = ''      # Personal Access Token

# Define dataset and image URL
CREATE_DATASET_ID = "ci_search_dataset"
DOG_IMG_URL = "https://samples.clarifai.com/dog.tiff"

# Create Clarifai application
app_obj = User(user_id=USER_ID, pat=PAT).create_app(app_id=APP_ID, base_workflow="General")

# Create a dataset
dataset_obj = app_obj.create_dataset(CREATE_DATASET_ID)

# Initialize inputs object
inp_obj = app_obj.inputs()

# Define metadata for the image
metadata = struct_pb2.Struct()
metadata.update({"Breed": "Saint Bernard"})

# Get input from URL and upload it
input_proto = inp_obj.get_input_from_url(
        dataset_id=CREATE_DATASET_ID,
        input_id="dog-tiff",
        image_url=DOG_IMG_URL,
        labels=["dog"],
        geo_info=[-30.0, 40.0],  # longitude, latitude
        metadata=metadata)
inp_obj.upload_inputs([input_proto])

# Define OR filter
or_filter = [{  # OR
              "concepts": [{
                  "name": "deer",
                  "value": 1
              }, {
                  "name": "dog",
                  "value": 1
              }]
          }]

# Perform search with OR filter
search = app_obj.search()
res = search.query(ranks=[{"image_url": "https://samples.clarifai.com/dog.tiff"}], filters=or_filter)

# Process search results
resp = list(res)
for r in resp:
    hit = r.hits[0].input.data.image.url
    break

# Display the image
print(hit)
hit_img = Image.open(requests.get(hit, stream=True).raw).resize((300,250))
display(hit_img)

import { Input, Search, User } from "clarifai-nodejs";


const appId = "test_app"; // Placeholder for application ID

const dogImgUrl = "https://samples.clarifai.com/dog.tiff";

// Initialize a User object with your credentials
const client = new User({
  userId: process.env.CLARIFAI_USER_ID,
  pat: process.env.CLARIFAI_PAT,
  appId,
});

// Create an application within Clarifai with the specified ID and base workflow
// The 'Universal' workflow is a general-purpose workflow that can handle various types of data
await client.createApp({
  appId,
  baseWorkflow: "Universal",
});

// Initialize an Input object to manage input data
const input = new Input({
  authConfig: {
    userId: process.env.CLARIFAI_USER_ID,
    pat: process.env.CLARIFAI_PAT,
    appId,
  },
});

// Define metadata for the image
const metadata = { Breed: "Saint Bernard" };

// Get input from URL and upload it
const inputProto = Input.getInputFromUrl({
  inputId: "dogTiff",
  imageUrl: dogImgUrl,
  labels: ["dog"],
  geoInfo: { longitude: -30.0, latitude: 40.0 }, // longitude, latitude
  metadata,
});
await input.uploadInputs({ inputs: [inputProto] });

// Define OR filter
const orFilter = [
  {
    // OR
    concepts: [
      {
        name: "deer",
        value: 1,
      },
      {
        name: "dog",
        value: 1,
      },
    ],
  },
];

// Perform search with OR filter
const search = new Search({
  authConfig: {
    userId: process.env.CLARIFAI_USER_ID,
    pat: process.env.CLARIFAI_PAT,
    appId,
  },
  topK: 2,
  metric: "euclidean",
});
const res = search.query({
  ranks: [{ imageUrl: "https://samples.clarifai.com/dog.tiff" }],
  filters: orFilter, // Filter for images only
});

let hit;
// Process search results
for await (const r of res) {
  hit = r.hitsList?.[0]?.input?.data?.image?.url;
  break;
}

// Display the image
console.log(hit);

AND Search Operation

The AND operation enables you to refine search results by specifying multiple conditions that must all be satisfied at the same time.

For example, if a user searches for images containing both the concepts "dog" and "deer," only those images labeled with both concepts will be returned.

Python SDK
Node.js SDK

# Import necessary modules
from clarifai.client.search import Search
from clarifai.client.user import User
from google.protobuf import struct_pb2
from PIL import Image
import requests
from IPython.display import display

# Define user-specific credentials
USER_ID=''
APP_ID=''
PAT=''

# Define constants
CREATE_DATASET_ID = "ci_search_dataset"
DOG_IMG_URL = "https://samples.clarifai.com/dog.tiff"

# Create a new application
app_obj = User(user_id=USER_ID, pat=PAT).create_app(app_id=APP_ID, base_workflow="General")

# Create a new dataset
dataset_obj = app_obj.create_dataset(CREATE_DATASET_ID)

# Initialize Inputs object for uploading data
inp_obj = app_obj.inputs()

# Define metadata for the input
metadata = struct_pb2.Struct()
metadata.update({"Breed": "Saint Bernard"})

# Get input from URL and upload it to the dataset
input_proto = inp_obj.get_input_from_url(
        dataset_id=CREATE_DATASET_ID,
        input_id="dog-tiff",
        image_url=DOG_IMG_URL,
        labels=["dog"],
        geo_info=[-30.0, 40.0],  # longitude, latitude
        metadata=metadata)
inp_obj.upload_inputs([input_proto])

# Define an AND filter
and_filter = [
              {  # AND
                  "concepts": [{
                      "name": "dog",
                      "value": 1
                  }]
              },
              {
                  "concepts": [{
                      "name": "deer",
                      "value": 1
                  }]
              }
          ]

# Create a search object
search = app_obj.search()

# Perform a search query with the specified rank and AND filter
res = search.query(ranks=[{"image_url": "https://samples.clarifai.com/dog.tiff"}], filters=and_filter)

# Convert search results to a list
resp = list(res)

# Print the length of the search results
print(len(resp)) # Should be zero

import { Input, Search, User } from "clarifai-nodejs";


const appId = "test_app"; // Placeholder for application ID

const dogImgUrl = "https://samples.clarifai.com/dog.tiff";

// Initialize a User object with your credentials
const client = new User({
  userId: process.env.CLARIFAI_USER_ID,
  pat: process.env.CLARIFAI_PAT,
  appId,
});

// Create an application within Clarifai with the specified ID and base workflow
// The 'Universal' workflow is a general-purpose workflow that can handle various types of data
await client.createApp({
  appId,
  baseWorkflow: "Universal",
});

// Initialize an Input object to manage input data
const input = new Input({
  authConfig: {
    userId: process.env.CLARIFAI_USER_ID,
    pat: process.env.CLARIFAI_PAT,
    appId,
  },
});

// Define metadata for the image
const metadata = { Breed: "Saint Bernard" };

// Get input from URL and upload it
const inputProto = Input.getInputFromUrl({
  inputId: "dogTiff",
  imageUrl: dogImgUrl,
  labels: ["dog"],
  geoInfo: { longitude: -30.0, latitude: 40.0 }, // longitude, latitude
  metadata,
});
await input.uploadInputs({ inputs: [inputProto] });

// Define andFilter
const andFilter = [
  {
    // AND
    concepts: [
      {
        name: "dog",
        value: 1,
      },
    ],
  },
  {
    concepts: [
      {
        name: "deer",
        value: 1,
      },
    ],
  },
];

// Perform search with OR filter
const search = new Search({
  authConfig: {
    userId: process.env.CLARIFAI_USER_ID,
    pat: process.env.CLARIFAI_PAT,
    appId,
  },
  topK: 2,
  metric: "euclidean",
});
const res = search.query({
  ranks: [{ imageUrl: "https://samples.clarifai.com/dog.tiff" }],
  filters: andFilter, // Filter for images only
});

let hit;
// Process search results
for await (const r of res) {
  hit = r.hitsList?.[0]?.input?.data?.image?.url;
  break;
}

// Display the image
console.log(hit);

Combine Filter and Rank

When you combine both Filter and Rank, filter will be applied before ranking annotations. This is important because limiting the results set on large applications can speed up the overall query drastically when doing a ranking.

from clarifai.client.search import Search
from clarifai.client.input import Inputs
from PIL import Image
import requests
from IPython.display import display

# Define your Clarifai credentials
USER_ID = ''
APP_ID = ''
PAT = ''

# Initialize the Clarifai client with your credentials
client = User(user_id=USER_ID)

# Create an application within Clarifai with the specified ID and base workflow
# The 'Universal' workflow is a general-purpose workflow that can handle various types of data
app = client.create_app(app_id=APP_ID, base_workflow="Universal", pat=PAT)

# Initialize a search object for the specified user, application, and access token
s = Search(user_id=USER_ID, app_id=APP_ID, pat=PAT)

# Initialize an Inputs object for the specified user, application, and access token
inp_obj = Inputs(user_id=USER_ID, app_id=APP_ID, pat=PAT)

# Prepare an input protobuf message from the provided image URL
input_proto = inp_obj.get_input_from_url(
        input_id="dog-tiff",
        image_url="https://samples.clarifai.com/dog.tiff",
        labels=["dog"],
        geo_info=[-30.0, 40.0],  # longitude, latitude
)

# Upload the prepared input protobuf message to the Clarifai application
inp_obj.upload_inputs([input_proto])

# Perform a search query with specified ranks and filters
response = s.query(ranks=[{"image_url": "https://samples.clarifai.com/dog.tiff"}], filters=[{"concepts": [{'name':'dog','value':1}]}])

# Process the response to extract the URL of the first matching image
resp = list(response)
for r in resp:
    hit = r.hits[0].input.data.image.url
    break

# Print the URL of the matched image
print(hit)

# Open the matched image URL, resize it, and display it
hit_img = Image.open(requests.get(hit, stream=True).raw).resize((300,250))
display(hit_img)

import { Input, Search, User } from "clarifai-nodejs";


const appId = "test_app"; // Placeholder for application ID

// Initialize a User object with your credentials
const client = new User({
  userId: process.env.CLARIFAI_USER_ID,
  pat: process.env.CLARIFAI_PAT,
  appId,
});

// Create an application within Clarifai with the specified ID and base workflow
// The 'Universal' workflow is a general-purpose workflow that can handle various types of data
await client.createApp({
  appId,
  baseWorkflow: "Universal",
});

// Initialize an Input object to manage input data
const input = new Input({
  authConfig: {
    userId: process.env.CLARIFAI_USER_ID,
    pat: process.env.CLARIFAI_PAT,
    appId,
  },
});

// Prepare an input protobuf message from the provided image URL
const inputProto = Input.getInputFromUrl({
  inputId: "dogTiff",
  imageUrl: "https://samples.clarifai.com/dog.tiff",
  labels: ["dog"],
  geoInfo: {
    longitude: -30.0,
    latitude: 40.0,
  },
});

// Upload the prepared input protobuf message to the clarifai application
input.uploadInputs({ inputs: [inputProto] });

// Initialize a search object for the created application with top-k results set to 2
const search = new Search({
  authConfig: {
    userId: process.env.CLARIFAI_USER_ID,
    pat: process.env.CLARIFAI_PAT,
    appId,
  },
  topK: 2,
  metric: "euclidean",
});

// Perform a search query with specified ranks and filters
const response = search.query({
  ranks: [{ imageUrl: "https://samples.clarifai.com/dog.tiff" }],
  filters: [{ concepts: [{ name: "dog", value: 1 }] }],
});

// Process the response to extract the URL of the first matching image
let hit;
for await (const r of response) {
  hit = r.hitsList?.[0]?.input?.data?.image?.url;
  break;
}

// Print the URL of the matched image
console.log(hit);

################################################################################
# In this section, we set the user authentication, app ID, and the concepts we  
# we want to search by. Change these strings to run your own example.
################################################################################

USER_ID = 'YOUR_USER_ID_HERE'
# Your PAT (Personal Access Token) can be found in the Account's Security section
PAT = 'YOUR_PAT_HERE'
APP_ID = 'YOUR_APP_ID_HERE'
# Change these to search by your own concepts
CONCEPT_ID_1 = 'cat'
CONCEPT_ID_2 = 'dog'

##########################################################################
# YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
##########################################################################

from clarifai_grpc.channel.clarifai_channel import ClarifaiChannel
from clarifai_grpc.grpc.api import resources_pb2, service_pb2, service_pb2_grpc
from clarifai_grpc.grpc.api.status import status_code_pb2

channel = ClarifaiChannel.get_grpc_channel()
stub = service_pb2_grpc.V2Stub(channel)

metadata = (('authorization', 'Key ' + PAT),)

userDataObject = resources_pb2.UserAppIDSet(user_id=USER_ID, app_id=APP_ID) # The userDataObject is required when using a PAT

# Here we search for images which we labeled with "cat" and for which the General prediction model does not find
# a "dog" concept.
post_annotations_searches_response = stub.PostAnnotationsSearches(
    service_pb2.PostAnnotationsSearchesRequest(
        user_app_id=userDataObject,  
        searches = [
            resources_pb2.Search(
                query=resources_pb2.Query(
                    filters=[
                        resources_pb2.Filter(
                            annotation=resources_pb2.Annotation(
                                data=resources_pb2.Data(
                                    concepts=[  # You can search by multiple concepts
                                        resources_pb2.Concept(
                                            id=CONCEPT_ID_1,  # You could search by concept Name as well
                                            value=1  # Value of 0 will search for images that don't have the concept
                                        )
                                    ]
                                )
                            )
                        )
                    ],
                    ranks=[
                        resources_pb2.Rank(
                            annotation=resources_pb2.Annotation(
                                data=resources_pb2.Data(
                                    concepts=[  # You can search by multiple concepts
                                        resources_pb2.Concept(
                                            id=CONCEPT_ID_2,  # You could search by concept Name as well
                                            value=0  # Value of 0 will search for images that don't have the concept
                                        )
                                    ]
                                )
                            )
                        )
                    ]
                )
            )
        ],
        pagination=service_pb2.Pagination(per_page=2, page=1)
    ),
    metadata=metadata
)

if post_annotations_searches_response.status.code != status_code_pb2.SUCCESS:
    print(post_annotations_searches_response.status)    
    raise Exception("Post searches failed, status: " + post_annotations_searches_response.status.description)

print("Search result:")
for hit in post_annotations_searches_response.hits:
    print("\tScore %.2f for annotation: %s off input: %s" % (hit.score, hit.annotation.id, hit.input.id))

<!--index.html file-->

<script>
    ///////////////////////////////////////////////////////////////////////////////////
    // In this section, we set the user authentication, app ID, and the concepts we  
    // we want to search by. Change these strings to run your own example.
    //////////////////////////////////////////////////////////////////////////////////

    const USER_ID = 'YOUR_USER_ID_HERE';
    // Your PAT (Personal Access Token) can be found in the Account's Security section
    const PAT = 'YOUR_PAT_HERE';
    const APP_ID = 'YOUR_APP_ID_HERE';
    // Change these to search by your own concepts
    const CONCEPT_ID_1 = 'cat';
    const CONCEPT_ID_2 = 'dog';

    ///////////////////////////////////////////////////////////////////////////////////
    // YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
    ///////////////////////////////////////////////////////////////////////////////////

    const raw = JSON.stringify({
        "user_app_id": {
            "user_id": USER_ID,
            "app_id": APP_ID
        },
        "searches": [
            {
                "query": {
                    "filters": [
                        {
                            "annotation": {
                                "data": {
                                    "concepts": [
                                        {
                                            "id": CONCEPT_ID_1,
                                            "value": 1
                                        }
                                    ]
                                }
                            }
                        }
                    ],
                    "ranks": [
                        {
                            "annotation": {
                                "data": {
                                    "concepts": [
                                        {
                                            "id": CONCEPT_ID_2,
                                            "value": 0
                                        }
                                    ]
                                }
                            }
                        }
                    ]
                }
            }
        ]
    });

    const requestOptions = {
        method: 'POST',
        headers: {
            'Accept': 'application/json',
            'Authorization': 'Key ' + PAT
        },
        body: raw
    };

    fetch(`https://api.clarifai.com/v2/annotations/searches`, requestOptions)
        .then(response => response.text())
        .then(result => console.log(result))
        .catch(error => console.log('error', error));

</script>

//index.js file

///////////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, and the concepts we  
// we want to search by. Change these strings to run your own example.
//////////////////////////////////////////////////////////////////////////////////

const USER_ID = 'YOUR_USER_ID_HERE';
// Your PAT (Personal Access Token) can be found in the Account's Security section
const PAT = 'YOUR_PAT_HERE';
const APP_ID = 'YOUR_APP_ID_HERE';
// Change these to search by your own concepts
const CONCEPT_ID_1 = 'cat';
const CONCEPT_ID_2 = 'dog';

/////////////////////////////////////////////////////////////////////////////
// YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
/////////////////////////////////////////////////////////////////////////////

const { ClarifaiStub, grpc } = require("clarifai-nodejs-grpc");

const stub = ClarifaiStub.grpc();

// This will be used by every Clarifai endpoint call
const metadata = new grpc.Metadata();
metadata.set("authorization", "Key " + PAT);

// Here we search for images which we labeled with "cat" and for which the General prediction model does not find
// a "dog" concept.
stub.PostAnnotationsSearches(
    {
        user_app_id: {
            user_id: USER_ID,
            app_id: APP_ID
        },

        searches: [
            {
                query: {
                    filters: [
                        {
                            annotation: {
                                data: {
                                    concepts: [  // You can search by multiple concepts
                                        {
                                            id: CONCEPT_ID_1,  // You could search by concept Name as well
                                            value: 1  // Value of 0 will search for images that don't have the concept
                                        }
                                    ]
                                }
                            }
                        }
                    ],
                    ranks: [
                        {
                            annotation: {
                                data: {
                                    concepts: [  // You can search by multiple concepts
                                        {
                                            id: CONCEPT_ID_2,  // You could search by concept Name as well
                                            value: 0  // Value of 0 will search for images that don't have the concept
                                        }
                                    ]
                                }
                            }
                        }
                    ]
                }
            }
        ]
    },
    metadata,
    (err, response) => {
        if (err) {
            throw new Error(err);
        }
        console.log(response.status)

        if (response.status.code !== 10000) {
            throw new Error("Post annotations searches failed, status: " + response.status.description);
        }

        console.log("Search result:");
        for (const hit of response.hits) {
            console.log("\tScore " + hit.score + " for annotation: " + hit.annotation.id + " of input: ", hit.input.id);
        }
    }
);

package com.clarifai.example;

import com.clarifai.channel.ClarifaiChannel;
import com.clarifai.credentials.ClarifaiCallCredentials;
import com.clarifai.grpc.api.*;
import com.clarifai.grpc.api.status.StatusCode;

public class ClarifaiExample {

    ///////////////////////////////////////////////////////////////////////////////////
    // In this section, we set the user authentication, app ID, and the concepts we  
    // we want to search by. Change these strings to run your own example.
    //////////////////////////////////////////////////////////////////////////////////

    static final String USER_ID = "YOUR_USER_ID_HERE";
    //Your PAT (Personal Access Token) can be found in the portal under Authentication
    static final String PAT = "YOUR_PAT_HERE";
    static final String APP_ID = "YOUR_APP_ID_HERE";
    // Change these to search by your own concepts
    static final String CONCEPT_ID_1 = "cat";
    static final String CONCEPT_ID_2 = "dog";

    ///////////////////////////////////////////////////////////////////////////////////
    // YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
    ///////////////////////////////////////////////////////////////////////////////////

    public static void main(String[] args) {

        V2Grpc.V2BlockingStub stub = V2Grpc.newBlockingStub(ClarifaiChannel.INSTANCE.getGrpcChannel())
            .withCallCredentials(new ClarifaiCallCredentials(PAT));

        // Here we search for images which we labeled with "cat" and for which the General prediction model does not find
        // a "dog" concept.
        MultiSearchResponse postAnnotationsSearchesResponse = stub.postAnnotationsSearches(
            PostAnnotationsSearchesRequest.newBuilder()
            .setUserAppId(UserAppIDSet.newBuilder().setUserId(USER_ID).setAppId(APP_ID))
            .addSearches(
                Search.newBuilder().setQuery(
                    Query.newBuilder()
                    .addFilters(
                        Filter.newBuilder().setAnnotation(
                            Annotation.newBuilder().setData(
                                Data.newBuilder().addConcepts( // You can search by multiple concepts
                                    Concept.newBuilder()
                                    .setId(CONCEPT_ID_1) // You could search by concept Name as well
                                    .setValue(1f) // Value of 0 will search for images that don't have the concept
                                )
                            )
                        )
                    )
                    .addRanks(
                        Rank.newBuilder().setAnnotation(
                            Annotation.newBuilder().setData(
                                Data.newBuilder().addConcepts( // You can search by multiple concepts
                                    Concept.newBuilder()
                                    .setId(CONCEPT_ID_2) // You could search by concept Name as well
                                    .setValue(1f) // Value of 0 will search for images that don't have the concept
                                )
                            )
                        )
                    )
                )
            )
            .build()
        );

        if (postAnnotationsSearchesResponse.getStatus().getCode() != StatusCode.SUCCESS) {
            throw new RuntimeException("Post annotations searches failed, status: " + postAnnotationsSearchesResponse.getStatus());
        }

        System.out.println("Found inputs " + postAnnotationsSearchesResponse.getHitsCount() + ":");
        for (Hit hit: postAnnotationsSearchesResponse.getHitsList()) {
            System.out.printf("\tScore %.2f for annotation %s of input %s\n", hit.getScore(), hit.getAnnotation().getId(), hit.getInput().getId());
        }

    }

}

<?php

require __DIR__ . "/vendor/autoload.php";

////////////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, and the concepts we  
// we want to search by. Change these strings to run your own example.
////////////////////////////////////////////////////////////////////////////////////

$USER_ID = "YOUR_USER_ID_HERE";
// Your PAT (Personal Access Token) can be found in the Account's Security section
$PAT = "YOUR_PAT_HERE";
$APP_ID = "YOUR_APP_ID_HERE";
// Change these to search by your own concepts
$CONCEPT_ID_1 = "cat";
$CONCEPT_ID_2 = "dog";

///////////////////////////////////////////////////////////////////////////////////
// YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
///////////////////////////////////////////////////////////////////////////////////

use Clarifai\ClarifaiClient;
use Clarifai\Api\PostAnnotationsSearchesRequest;
use Clarifai\Api\Annotation;
use Clarifai\Api\Concept;
use Clarifai\Api\Data;
use Clarifai\Api\Filter;
use Clarifai\Api\Rank;
use Clarifai\Api\Query;
use Clarifai\Api\Search;
use Clarifai\Api\Status\StatusCode;
use Clarifai\Api\UserAppIDSet;

$client = ClarifaiClient::grpc();

$metadata = ["Authorization" => ["Key " . $PAT]];

$userDataObject = new UserAppIDSet([
    "user_id" => $USER_ID,
    "app_id" => $APP_ID
]);

// Let's make a RPC call to the Clarifai platform. It uses the opened gRPC client channel to communicate a
// request and then wait for the response
[$response, $status] = $client->PostAnnotationsSearches(
    // The request object carries the request along with the request status and other metadata related to the request itself
    new PostAnnotationsSearchesRequest([
        "user_app_id" => $userDataObject,
        "searches" => [
            new Search([
                "query" => new Query([
                    "filters" => [
                        new Filter([
                            "annotation" => new Annotation([
                                "data" => new Data([
                                    "concepts" => [  # You can search by multiple concepts
                                        new Concept([
                                            "id" => $CONCEPT_ID_1, # You could search by concept Name as well
                                            "value" => 1. # Value of 0 will search for images that don't have the concept
                                        ])
                                    ]
                                ])
                            ])
                        ])
                    ],
                    "ranks" => [
                        new Rank([
                            "annotation" => new Annotation([
                                "data" => new Data([
                                    "concepts" => [  # You can search by multiple concepts
                                        new Concept([
                                            "id" => $CONCEPT_ID_2, # You could search by concept Name as well
                                            "value" => 0 # Value of 0 will search for images that don't have the concept
                                        ])
                                    ]
                                ])
                            ])
                        ])
                    ]
                ])
            ])
        ]
    ]),
    $metadata
)->wait();

// A response is returned and the first thing we do is check the status of it
// A successful response will have a status code of 0; otherwise, there is some error
if ($status->code !== 0) {
    throw new Exception("Error: {$status->details}");
}
// In addition to the RPC response status, there is a Clarifai API status that reports if the operation was a success or failure 
// (not just that the communication was successful)
if ($response->getStatus()->getCode() != StatusCode::SUCCESS) {
    print $response->getStatus()->getDetails();
    throw new Exception("Failure response: " . $response->getStatus()->getDescription());
}

echo "Search result:\n";
foreach ($response->getHits() as $hit) {
    printf("\tScore %.2f for annotation: %s off input: %s\n", $hit->getScore(), $hit->getAnnotation()->getId(), $hit->getInput()->getId());
}

?>

# Here we search for images which we labeled with "cat" and for which the General prediction model does not find
# a "dog" concept.

curl -X POST "https://api.clarifai.com/v2/users/YOUR_USER_ID_HERE/apps/YOUR_APP_ID_HERE/annotations/searches" \
  -H "Authorization: Key YOUR_PAT_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "searches": [
      {
        "query": {
          "filters": [
            {
              "annotation": {
                "data": {
                  "concepts": [
                    {
                      "id":"cat",
                      "value": 1
                    }
                  ]
                }
              }
            }
          ],
          "ranks": [
            {
              "annotation": {
                "data": {
                  "concepts": [
                    {
                      "id":"dog",
                      "value": 0
                    }
                  ]
                }
              }
            }
          ]
        }
      }
    ]
  }'

Combine Filter by Metadata and Rank

You can also search over custom metadata and easily rank the results.

################################################################################
# In this section, we set the user authentication, app ID, and concept ID.
# Change these strings to run your own example.
###############################################################################

USER_ID = "YOUR_USER_ID_HERE"
# Your PAT (Personal Access Token) can be found in the Account's Security section
PAT = "YOUR_PAT_HERE"
APP_ID = "YOUR_APP_ID_HERE"
# Change this to rank the filtered results by your own concept
CONCEPT_ID = "cat"

##########################################################################
# YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
##########################################################################

from clarifai_grpc.channel.clarifai_channel import ClarifaiChannel
from clarifai_grpc.grpc.api import resources_pb2, service_pb2, service_pb2_grpc
from clarifai_grpc.grpc.api.status import status_code_pb2
from google.protobuf.struct_pb2 import Struct

channel = ClarifaiChannel.get_grpc_channel()
stub = service_pb2_grpc.V2Stub(channel)

metadata = (("authorization", "Key " + PAT),)

userDataObject = resources_pb2.UserAppIDSet(
    user_id=USER_ID, app_id=APP_ID
)  # The userDataObject is required when using a PAT

search_metadata = Struct()
search_metadata.update({"type": "animal"})

post_annotations_searches_response = stub.PostAnnotationsSearches(
    service_pb2.PostAnnotationsSearchesRequest(
        user_app_id=userDataObject,
        searches=[
            resources_pb2.Search(
                query=resources_pb2.Query(
                    filters=[
                        resources_pb2.Filter(
                            annotation=resources_pb2.Annotation(
                                data=resources_pb2.Data(metadata=search_metadata)
                            )
                        )
                    ],
                    ranks=[
                        resources_pb2.Rank(
                            annotation=resources_pb2.Annotation(
                                data=resources_pb2.Data(
                                    concepts=[  # You can search by multiple concepts.
                                        resources_pb2.Concept(
                                            id=CONCEPT_ID,  # You could search by concept Name as well.
                                            value=1,  # Value of 0 will search for images that don't have the concept.
                                        )
                                    ]
                                )
                            )
                        )
                    ],
                )
            )
        ],
        pagination=service_pb2.Pagination(per_page=2, page=1),
    ),
    metadata=metadata,
)

if post_annotations_searches_response.status.code != status_code_pb2.SUCCESS:
    raise Exception("Post searches failed, status: " + post_annotations_searches_response.status.description)

print("Search result:")
for hit in post_annotations_searches_response.hits:
    print("\tScore %.2f for annotation: %s off input: %s" % (hit.score, hit.annotation.id, hit.input.id))

<!--index.html file-->

<script>
    ///////////////////////////////////////////////////////////////////////////////////
    // In this section, we set the user authentication, app ID, and concept ID.
    // Change these strings to run your own example.
    ///////////////////////////////////////////////////////////////////////////////////

    const USER_ID = "YOUR_USER_ID_HERE";
    // Your PAT (Personal Access Token) can be found in the Account's Security section
    const PAT = "YOUR_PAT_HERE";
    const APP_ID = "YOUR_APP_ID_HERE";
    // Change this to rank the filtered results by your own concept
    const CONCEPT_ID = "cat";

    ///////////////////////////////////////////////////////////////////////////////////
    // YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
    ///////////////////////////////////////////////////////////////////////////////////

    const raw = JSON.stringify({
        "user_app_id": {
            "user_id": USER_ID,
            "app_id": APP_ID
        },
        "searches": [
            {
                "query": {
                    "filters": [
                        {
                            "annotation": {
                                "data": {
                                    "metadata": {
                                        "type": "animal"
                                    }
                                }
                            }
                        }
                    ],
                    "ranks": [
                        {
                            "annotation": {
                                "data": {
                                    "concepts": [
                                        {
                                            "id": CONCEPT_ID,
                                            "value": 1
                                        }
                                    ]
                                }
                            }
                        }
                    ]
                }
            }
        ]
    });

    const requestOptions = {
        method: 'POST',
        headers: {
            'Accept': 'application/json',
            'Authorization': 'Key ' + PAT
        },
        body: raw
    };

    fetch(`https://api.clarifai.com/v2/annotations/searches`, requestOptions)
        .then(response => response.text())
        .then(result => console.log(result))
        .catch(error => console.log('error', error));
</script>

// index.js file

//////////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, and concept ID.
// Change these strings to run your own example.
////////////////////////////////////////////////////////////////////////////////

const USER_ID = "YOUR_USER_ID_HERE";
// Your PAT (Personal Access Token) can be found in the Account's Security section
const PAT = "YOUR_PAT_HERE";
const APP_ID = "YOUR_APP_ID_HERE";
// Change this to rank the filtered results by your own concept
const CONCEPT_ID = "cat";

/////////////////////////////////////////////////////////////////////////////
// YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
/////////////////////////////////////////////////////////////////////////////

const { ClarifaiStub, grpc } = require("clarifai-nodejs-grpc");

const stub = ClarifaiStub.grpc();

// This will be used by every Clarifai endpoint call
const metadata = new grpc.Metadata();
metadata.set("authorization", "Key " + PAT);

stub.PostAnnotationsSearches({
    user_app_id: {
        user_id: USER_ID,
        app_id: APP_ID
    },
    searches: [{
        query: {
            filters: [{
                annotation: {
                    data: {
                        metadata: {
                            type: "animal"
                        }
                    }
                }
            }],
            ranks: [{
                annotation: {
                    data: {
                        concepts: [ // You can search by multiple concepts.
                            {
                                id: CONCEPT_ID, // You could search by concept Name as well.
                                value: 1 // Value of 0 will search for images that don't have the concept
                            }
                        ]
                    }
                }
            }]
        }
    }]
},
metadata,
(err, response) => {
    if (err) {
        throw new Error(err);
    }

    if (response.status.code !== 10000) {
        throw new Error("Post annotations searches failed, status: " + response.status.description);
    }

    console.log("Search result:");
    for (const hit of response.hits) {
        console.log("\tScore " + hit.score + " for annotation: " + hit.annotation.id + " of input: ", hit.input.id);
    }
});

package com.clarifai.example;

import com.clarifai.channel.ClarifaiChannel;
import com.clarifai.credentials.ClarifaiCallCredentials;
import com.clarifai.grpc.api.*;
import com.clarifai.grpc.api.status.StatusCode;
import com.google.protobuf.Struct;
import com.google.protobuf.Value;

public class ClarifaiExample {

    ///////////////////////////////////////////////////////////////////////////////
    // In this section, we set the user authentication, app ID, and concept ID.
	// Change these strings to run your own example.
    //////////////////////////////////////////////////////////////////////////////

    static final String USER_ID = "YOUR_USER_ID_HERE";
    //Your PAT (Personal Access Token) can be found in the portal under Authentication
    static final String PAT = "YOUR_PAT_HERE";
    static final String APP_ID = "YOUR_APP_ID_HERE";
    // Change this to rank the filtered results by your own concept
    static final String CONCEPT_ID = "cat";

    ///////////////////////////////////////////////////////////////////////////////////
    // YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
    ///////////////////////////////////////////////////////////////////////////////////

    public static void main(String[] args) {

        V2Grpc.V2BlockingStub stub = V2Grpc.newBlockingStub(ClarifaiChannel.INSTANCE.getGrpcChannel())
            .withCallCredentials(new ClarifaiCallCredentials(PAT));

        MultiSearchResponse postAnnotationsSearchesResponse = stub.postAnnotationsSearches(
            PostAnnotationsSearchesRequest.newBuilder()
            .setUserAppId(UserAppIDSet.newBuilder().setUserId(USER_ID).setAppId(APP_ID))
            .addSearches(
                Search.newBuilder().setQuery(
                    Query.newBuilder().addFilters(
                        Filter.newBuilder().setAnnotation(
                            Annotation.newBuilder().setData(
                                Data.newBuilder().setMetadata(
                                    Struct.newBuilder()
                                    .putFields("type", Value.newBuilder().setStringValue("animal").build())
                                )
                            )
                        )
                    )
                   .addRanks(
                            Rank.newBuilder().setAnnotation(
                                Annotation.newBuilder().setData(
                                    Data.newBuilder().addConcepts( // You can search by multiple concepts
                                        Concept.newBuilder()
                                        .setId(CONCEPT_ID) // You could search by concept Name as well
                                        .setValue(1f) // Value of 0 will search for images that don't have the concept
                                    )
                                )
                            )
                        )
                )
            )
            .build()
        );

        if (postAnnotationsSearchesResponse.getStatus().getCode() != StatusCode.SUCCESS) {
            throw new RuntimeException("Post annotations searches failed, status: " + postAnnotationsSearchesResponse.getStatus());
        }

        System.out.println("Found inputs " + postAnnotationsSearchesResponse.getHitsCount() + ":");
        for (Hit hit : postAnnotationsSearchesResponse.getHitsList()) {
            System.out.printf("\tScore %.2f for annotation %s of input %s\n", hit.getScore(), hit.getAnnotation().getId(), hit.getInput().getId());
        }

    }

}

<?php

require __DIR__ . "/vendor/autoload.php";

//////////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, and concept ID.
// Change these strings to run your own example.
////////////////////////////////////////////////////////////////////////////////

$USER_ID = "YOUR_USER_ID_HERE";
// Your PAT (Personal Access Token) can be found in the Account's Security section
$PAT = "YOUR_PAT_HERE";
$APP_ID = "YOUR_APP_ID_HERE";
// Change this to rank the filtered results by your own concept
$CONCEPT_ID = "cat";

///////////////////////////////////////////////////////////////////////////////////
// YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
///////////////////////////////////////////////////////////////////////////////////

use Clarifai\ClarifaiClient;
use Clarifai\Api\PostAnnotationsSearchesRequest;
use Clarifai\Api\Annotation;
use Clarifai\Api\Data;
use Clarifai\Api\Filter;
use Clarifai\Api\Query;
use Clarifai\Api\Search;
use Clarifai\Api\Concept;
use Clarifai\Api\Rank;
use Clarifai\Api\Status\StatusCode;
use Clarifai\Api\UserAppIDSet;
use Google\Protobuf\Struct;

$client = ClarifaiClient::grpc();

$metadata = ["Authorization" => ["Key " . $PAT]];

$userDataObject = new UserAppIDSet([
    "user_id" => $USER_ID,
    "app_id" => $APP_ID
]);

// create Struct instance
$params = new Struct();
$params->type = "animal";

// Let's make a RPC call to the Clarifai platform. It uses the opened gRPC client channel to communicate a
// request and then wait for the response
[$response, $status] = $client->PostAnnotationsSearches(
    // The request object carries the request along with the request status and other metadata related to the request itself
    new PostAnnotationsSearchesRequest([
        "user_app_id" => $userDataObject,
        "searches" => [
            new Search([
                "query" => new Query([
                    "filters" => [
                        new Filter([
                            "annotation" => new Annotation([
                                "data" => new Data([
                                    "metadata" => $params
                                ])
                            ])
                        ])
                    ],
                    "ranks" => [
                        new Rank([
                            "annotation" => new Annotation([
                                "data" => new Data([
                                    "concepts" => [  // You can search by multiple concepts
                                        new Concept([
                                            "id" => $CONCEPT_ID, // You could search by concept name as well
                                            "value" => 1 // Value of 0 will search for images that don't have the concept
                                        ])
                                    ]
                                ])
                            ])
                        ])
                    ]
                ])
            ])
        ]
    ]),
    $metadata
)->wait();

// A response is returned and the first thing we do is check the status of it
// A successful response will have a status code of 0; otherwise, there is some error
if ($status->code !== 0) {
    throw new Exception("Error: {$status->details}");
}
// In addition to the RPC response status, there is a Clarifai API status that reports if the operation was a success or failure 
// (not just that the communication was successful)
if ($response->getStatus()->getCode() != StatusCode::SUCCESS) {
    print $response->getStatus()->getDetails();
    throw new Exception("Failure response: " . $response->getStatus()->getDescription());
}

echo "Search result:\n";
foreach ($response->getHits() as $hit) {
    printf("\tScore %.2f for annotation: %s off input: %s\n", $hit->getScore(), $hit->getAnnotation()->getId(), $hit->getInput()->getId());
}

?>

curl -X POST "https://api.clarifai.com/v2/users/YOUR_USER_ID_HERE/apps/YOUR_APP_ID_HERE/annotations/searches" \
  -H "Authorization: Key YOUR_PAT_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "searches": [
      {
        "query": {
          "filters": [
            {
              "annotation": {
                "data": {
                  "metadata": {
                    "type": "animal"
                  }
                }
              }
            }
          ],
          "ranks": [
            {
              "annotation": {
                "data": {
                  "concepts": [
                    {
                      "id": "cat",
                      "value": 1
                    }
                  ]
                }
              }
            }
          ]
        }
      }
    ]
  }'

Negate Search Criteria

You can find all the data that is NOT similar to a given criteria.

################################################################################
# In this section, we set the user authentication, app ID, and the concept we  
# we want to search by. Change these strings to run your own example.
################################################################################

USER_ID = 'YOUR_USER_ID_HERE'
# Your PAT (Personal Access Token) can be found in the Account's Security section
PAT = 'YOUR_PAT_HERE'
APP_ID = 'YOUR_APP_ID_HERE'
# Change this to search by your own concept
CONCEPT_NAME = 'cat'

##########################################################################
# YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
##########################################################################

from clarifai_grpc.channel.clarifai_channel import ClarifaiChannel
from clarifai_grpc.grpc.api import resources_pb2, service_pb2, service_pb2_grpc
from clarifai_grpc.grpc.api.status import status_code_pb2

channel = ClarifaiChannel.get_grpc_channel()
stub = service_pb2_grpc.V2Stub(channel)

metadata = (('authorization', 'Key ' + PAT),)

userDataObject = resources_pb2.UserAppIDSet(user_id=USER_ID, app_id=APP_ID) # The userDataObject is required when using a PAT

post_annotations_searches_response = stub.PostAnnotationsSearches(
    service_pb2.PostAnnotationsSearchesRequest(
        user_app_id=userDataObject,  
        searches = [
            resources_pb2.Search(
                query=resources_pb2.Query(
                    filters=[
                        resources_pb2.Filter(
                            annotation=resources_pb2.Annotation(
                                data=resources_pb2.Data(
                                    concepts=[  # You can search by multiple concepts
                                        resources_pb2.Concept(
                                            name=CONCEPT_NAME,  # You could search by concept id as well
                                        )
                                    ]
                                )
                            ),
                            negate=True
                        )
                    ]
                )
            )
        ]
    ),
    metadata=metadata
)

if post_annotations_searches_response.status.code != status_code_pb2.SUCCESS:
    print(post_annotations_searches_response.status)    
    raise Exception("Post searches failed, status: " + post_annotations_searches_response.status.description)

print("Search result:")
for hit in post_annotations_searches_response.hits:
    print("\tScore %.2f for annotation: %s off input: %s" % (hit.score, hit.annotation.id, hit.input.id))
    

<!--index.html file-->

<script>
    ///////////////////////////////////////////////////////////////////////////////////
    // In this section, we set the user authentication, app ID, and the concept we  
    // we want to search by. Change these strings to run your own example.
    //////////////////////////////////////////////////////////////////////////////////

    const USER_ID = 'YOUR_USER_ID_HERE';
    // Your PAT (Personal Access Token) can be found in the Account's Security section
    const PAT = 'YOUR_PAT_HERE';
    const APP_ID = 'YOUR_APP_ID_HERE';
    // Change this to search by your own concept
    const CONCEPT_NAME = 'cat';
   
    ///////////////////////////////////////////////////////////////////////////////////
    // YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
    ///////////////////////////////////////////////////////////////////////////////////

    const raw = JSON.stringify({
        "user_app_id": {
            "user_id": USER_ID,
            "app_id": APP_ID
        },
        "searches": [
            {
                "query": {
                    "filters": [
                        {
                            "annotation": {
                                "data": {
                                    "concepts": [
                                        {
                                            "name": CONCEPT_NAME                                            
                                        }
                                    ]
                                }
                            },
                            "negate" : true
                        }
                    ]
                }
            }
        ]
    });

    const requestOptions = {
        method: 'POST',
        headers: {
            'Accept': 'application/json',
            'Authorization': 'Key ' + PAT
        },
        body: raw
    };

    fetch(`https://api.clarifai.com/v2/annotations/searches`, requestOptions)
        .then(response => response.text())
        .then(result => console.log(result))
        .catch(error => console.log('error', error));

</script>

//index.js file

///////////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, and the concept we  
// we want to search by. Change these strings to run your own example.
//////////////////////////////////////////////////////////////////////////////////

const USER_ID = 'YOUR_USER_ID_HERE';
// Your PAT (Personal Access Token) can be found in the Account's Security section
const PAT = 'YOUR_PAT_HERE';
const APP_ID = 'YOUR_APP_ID_HERE';
// Change this to search by your own concept
const CONCEPT_NAME = 'cat';

/////////////////////////////////////////////////////////////////////////////
// YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
/////////////////////////////////////////////////////////////////////////////

const { ClarifaiStub, grpc } = require("clarifai-nodejs-grpc");

const stub = ClarifaiStub.grpc();

// This will be used by every Clarifai endpoint call
const metadata = new grpc.Metadata();
metadata.set("authorization", "Key " + PAT);

stub.PostAnnotationsSearches(
    {
        user_app_id: {
            user_id: USER_ID,
            app_id: APP_ID
        },

        searches: [
            {
                query: {
                    filters: [
                        {
                            annotation: {
                                data: {
                                    concepts: [  // You can search by multiple concepts
                                        {
                                            name: CONCEPT_NAME  // You could search by concept id as well                                           
                                        }
                                    ]
                                }
                            },
                            negate: true
                        }
                    ]
                }
            }
        ]
    },
    metadata,
    (err, response) => {
        if (err) {
            throw new Error(err);
        }
        console.log(response.status)

        if (response.status.code !== 10000) {
            throw new Error("Post annotations searches failed, status: " + response.status.description);
        }

        console.log("Search result:");
        for (const hit of response.hits) {
            console.log("\tScore " + hit.score + " for annotation: " + hit.annotation.id + " of input: ", hit.input.id);
        }
    }
);

package com.clarifai.example;

import com.clarifai.channel.ClarifaiChannel;
import com.clarifai.credentials.ClarifaiCallCredentials;
import com.clarifai.grpc.api.*;
import com.clarifai.grpc.api.status.StatusCode;

public class ClarifaiExample {

    ///////////////////////////////////////////////////////////////////////////////////
    // In this section, we set the user authentication, app ID, and the concept we  
    // we want to search by. Change these strings to run your own example.
    //////////////////////////////////////////////////////////////////////////////////

    static final String USER_ID = "YOUR_USER_ID_HERE";
    //Your PAT (Personal Access Token) can be found in the portal under Authentication
    static final String PAT = "YOUR_PAT_HERE";
    static final String APP_ID = "YOUR_APP_ID_HERE";
    // Change this to search by your own concept
    static final String CONCEPT_NAME = "cat";
   
    ///////////////////////////////////////////////////////////////////////////////////
    // YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
    ///////////////////////////////////////////////////////////////////////////////////

    public static void main(String[] args) {

        V2Grpc.V2BlockingStub stub = V2Grpc.newBlockingStub(ClarifaiChannel.INSTANCE.getGrpcChannel())
            .withCallCredentials(new ClarifaiCallCredentials(PAT));
       
        MultiSearchResponse postAnnotationsSearchesResponse = stub.postAnnotationsSearches(
            PostAnnotationsSearchesRequest.newBuilder()
            .setUserAppId(UserAppIDSet.newBuilder().setUserId(USER_ID).setAppId(APP_ID))
            .addSearches(
                Search.newBuilder().setQuery(
                    Query.newBuilder()
                    .addFilters(
                        Filter.newBuilder().setAnnotation(
                            Annotation.newBuilder().setData(
                                Data.newBuilder().addConcepts( // You can search by multiple concepts
                                    Concept.newBuilder()
                                    .setName(CONCEPT_NAME) // You could search by concept id as well                                   
                                )
                            )                                                      
                            
                        )
                        .setNegate(true)
                    ) 
                )
            )
            .build()
        );

        if (postAnnotationsSearchesResponse.getStatus().getCode() != StatusCode.SUCCESS) {
            throw new RuntimeException("Post annotations searches failed, status: " + postAnnotationsSearchesResponse.getStatus());
        }

        System.out.println("Found inputs " + postAnnotationsSearchesResponse.getHitsCount() + ":");
        for (Hit hit: postAnnotationsSearchesResponse.getHitsList()) {
            System.out.printf("\tScore %.2f for annotation %s of input %s\n", hit.getScore(), hit.getAnnotation().getId(), hit.getInput().getId());
        }

    }

}

<?php

require __DIR__ . "/vendor/autoload.php";

////////////////////////////////////////////////////////////////////////////////////
// In this section, we set the user authentication, app ID, and the concept we  
// we want to search by. Change these strings to run your own example.
////////////////////////////////////////////////////////////////////////////////////

$USER_ID = "YOUR_USER_ID_HERE";
// Your PAT (Personal Access Token) can be found in the Account's Security section
$PAT = "YOUR_PAT_HERE";
$APP_ID = "YOUR_APP_ID_HERE";
// Change this to search by your own concept
$CONCEPT_NAME = "cat";

///////////////////////////////////////////////////////////////////////////////////
// YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
///////////////////////////////////////////////////////////////////////////////////

use Clarifai\ClarifaiClient;
use Clarifai\Api\PostAnnotationsSearchesRequest;
use Clarifai\Api\Annotation;
use Clarifai\Api\Concept;
use Clarifai\Api\Data;
use Clarifai\Api\Filter;
use Clarifai\Api\Query;
use Clarifai\Api\Search;
use Clarifai\Api\Status\StatusCode;
use Clarifai\Api\UserAppIDSet;

$client = ClarifaiClient::grpc();

$metadata = ["Authorization" => ["Key " . $PAT]];

$userDataObject = new UserAppIDSet([
    "user_id" => $USER_ID,
    "app_id" => $APP_ID
]);

// Let's make a RPC call to the Clarifai platform. It uses the opened gRPC client channel to communicate a
// request and then wait for the response
[$response, $status] = $client->PostAnnotationsSearches(
    // The request object carries the request along with the request status and other metadata related to the request itself
    new PostAnnotationsSearchesRequest([
        "user_app_id" => $userDataObject,
        "searches" => [
            new Search([
                "query" => new Query([
                    "filters" => [
                        new Filter([
                            "annotation" => new Annotation([
                                "data" => new Data([
                                    "concepts" => [  # You can search by multiple concepts
                                        new Concept([
                                            "name" => $CONCEPT_NAME # You could search by concept Name as well
                                        ])
                                    ]
                                ])
                            ]),
                            "negate" => true
                        ])
                    ]
                ])
            ])
        ]
    ]),
    $metadata
)->wait();

// A response is returned and the first thing we do is check the status of it
// A successful response will have a status code of 0; otherwise, there is some error
if ($status->code !== 0) {
    throw new Exception("Error: {$status->details}");
}
// In addition to the RPC response status, there is a Clarifai API status that reports if the operation was a success or failure 
// (not just that the communication was successful)
if ($response->getStatus()->getCode() != StatusCode::SUCCESS) {
    print $response->getStatus()->getDetails();
    throw new Exception("Failure response: " . $response->getStatus()->getDescription());
}

echo "Search result:\n";
foreach ($response->getHits() as $hit) {
    printf("\tScore %.2f for annotation: %s off input: %s\n", $hit->getScore(), $hit->getAnnotation()->getId(), $hit->getInput()->getId());
}

?>

curl -X POST "https://api.clarifai.com/v2/users/YOUR_USER_ID_HERE/apps/YOUR_APP_ID_HERE/annotations/searches" \
  -H "Authorization: Key YOUR_PAT_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "searches": [
      {
        "query": {
          "filters": [
            {
              "annotation": {
                "data": {
                  "concepts": [
                    {
                      "name":"cat"                      
                    }
                  ]
                }
              },
              "negate": true
            }
          ]
        }
      }
    ]
  }'

Find Duplicate Images in Dataset

Here's how you can use the PostInputsSearches endpoint to identify near-duplicate images within a given dataset.

You can also use the min_value threshold parameter to refine the search results, ensuring that only images surpassing a specified minimum probability resemblance score are included in the output. .

cURL

curl -X POST "https://api.clarifai.com/v2/users/YOUR_USER_ID_HERE/apps/YOUR_APP_ID_HERE/inputs/searches" \
  -H "Authorization: Key YOUR_PAT_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "searches": [
      {
        "query": {
          "filters": [
            {
              "input": {
                "dataset_ids": ["YOUR_DATASET_ID_HERE"]
              }
            }
          ],
          "ranks": [
            {
              "annotation": {
                "data": {
                  "image": {
                    "url": "https://samples.clarifai.com/metro-north.jpg"
                  }
                }
              }
            }
          ]
        },
        "min_value": 0.95
      }
    ]
  }'

OR Search Operation​

AND Search Operation​

Combine Filter and Rank​

Combine Filter by Metadata and Rank​

Negate Search Criteria​

Find Duplicate Images in Dataset​

What did you think of this doc?