Manage Functions

Important

This page only shows some frequently used operations.

  • For the latest and complete information about Pulsar admin, including commands, flags, descriptions, and more, see Pulsar admin doc

  • For the latest and complete information about REST API, including parameters, responses, samples, and more, see REST API doc.

  • For the latest and complete information about Java admin API, including classes, methods, descriptions, and more, see Java admin API doc.

Pulsar Functions are lightweight compute processes that

  • consume messages from one or more Pulsar topics
  • apply a user-supplied processing logic to each message
  • publish the results of the computation to another topic

Functions can be managed via the following methods.

MethodDescription
Admin CLIThe functions command of the pulsar-admin tool.
REST APIThe /admin/v3/functions endpoint of the admin REST API.
Java Admin APIThe functions method of the PulsarAdmin object in the Java API.

Function resources

You can perform the following operations on functions.

Create a function

You can create a Pulsar function in cluster mode (deploy it on a Pulsar cluster) using Admin CLI, REST API or Java Admin API.

  • Admin CLI
  • REST API
  • Java Admin API

Use the create subcommand.

Example

  2. $ pulsar-admin functions create \
  3.   --tenant public \
  4.   --namespace default \
  5.   --name (the name of Pulsar Functions) \
  6.   --inputs test-input-topic \
  7.   --output persistent://public/default/test-output-topic \
  8.   --classname org.apache.pulsar.functions.api.examples.ExclamationFunction \
  9.   --jar /examples/api-examples.jar

POST /admin/v3/functions/:tenant/:namespace/:functionName?version=2.10.0

  2. FunctionConfig functionConfig = new FunctionConfig();
  3. functionConfig.setTenant(tenant);
  4. functionConfig.setNamespace(namespace);
  5. functionConfig.setName(functionName);
  6. functionConfig.setRuntime(FunctionConfig.Runtime.JAVA);
  7. functionConfig.setParallelism(1);
  8. functionConfig.setClassName("org.apache.pulsar.functions.api.examples.ExclamationFunction");
  9. functionConfig.setProcessingGuarantees(FunctionConfig.ProcessingGuarantees.ATLEAST_ONCE);
  10. functionConfig.setTopicsPattern(sourceTopicPattern);
  11. functionConfig.setSubName(subscriptionName);
  12. functionConfig.setAutoAck(true);
  13. functionConfig.setOutput(sinkTopic);
  14. admin.functions().createFunction(functionConfig, fileName);

Update a function

You can update a Pulsar function that has been deployed to a Pulsar cluster using Admin CLI, REST API or Java Admin API.

  • Admin CLI
  • REST Admin API
  • Java Admin API

Use the update subcommand.

Example

  2. $ pulsar-admin functions update \
  3.   --tenant public \
  4.   --namespace default \
  5.   --name (the name of Pulsar Functions) \
  6.   --output persistent://public/default/update-output-topic \
  7.   # other options

PUT /admin/v3/functions/:tenant/:namespace/:functionName?version=2.10.0

  2. FunctionConfig functionConfig = new FunctionConfig();
  3. functionConfig.setTenant(tenant);
  4. functionConfig.setNamespace(namespace);
  5. functionConfig.setName(functionName);
  6. functionConfig.setRuntime(FunctionConfig.Runtime.JAVA);
  7. functionConfig.setParallelism(1);
  8. functionConfig.setClassName("org.apache.pulsar.functions.api.examples.ExclamationFunction");
  9. UpdateOptions updateOptions = new UpdateOptions();
  10. updateOptions.setUpdateAuthData(updateAuthData);
  11. admin.functions().updateFunction(functionConfig, userCodeFile, updateOptions);

Start an instance of a function

You can start a stopped function instance with instance-id using Admin CLI, REST API or Java Admin API.

  • Admin CLI
  • REST API
  • Java Admin API

Use the start subcommand.

  2. $ pulsar-admin functions start \
  3.   --tenant public \
  4.   --namespace default \
  5.   --name (the name of Pulsar Functions) \
  6.   --instance-id 1

POST /admin/v3/functions/:tenant/:namespace/:functionName/:instanceId/start?version=2.10.0

  2. admin.functions().startFunction(tenant, namespace, functionName, Integer.parseInt(instanceId));

Start all instances of a function

You can start all stopped function instances using Admin CLI, REST API or Java Admin API.

  • Admin CLI
  • REST API
  • Java

Use the start subcommand.

Example

  2. $ pulsar-admin functions start \
  3.   --tenant public \
  4.   --namespace default \
  5.   --name (the name of Pulsar Functions) \

POST /admin/v3/functions/:tenant/:namespace/:functionName/start?version=2.10.0

  2. admin.functions().startFunction(tenant, namespace, functionName);

Stop an instance of a function

You can stop a function instance with instance-id using Admin CLI, REST API or Java Admin API.

  • Admin CLI
  • REST API
  • Java Admin API

Use the stop subcommand.

Example

  2. $ pulsar-admin functions stop \
  3.   --tenant public \
  4.   --namespace default \
  5.   --name (the name of Pulsar Functions) \
  6.   --instance-id 1

POST /admin/v3/functions/:tenant/:namespace/:functionName/:instanceId/stop?version=2.10.0

  2. admin.functions().stopFunction(tenant, namespace, functionName, Integer.parseInt(instanceId));

Stop all instances of a function

You can stop all function instances using Admin CLI, REST API or Java Admin API.

  • Admin CLI
  • REST API
  • Java Admin API

Use the stop subcommand.

Example

  2. $ pulsar-admin functions stop \
  3.   --tenant public \
  4.   --namespace default \
  5.   --name (the name of Pulsar Functions) \

POST /admin/v3/functions/:tenant/:namespace/:functionName/stop?version=2.10.0

  2. admin.functions().stopFunction(tenant, namespace, functionName);

Restart an instance of a function

Restart a function instance with instance-id using Admin CLI, REST API or Java Admin API.

  • Admin CLI
  • REST API
  • Java Admin API

Use the restart subcommand.

Example

  2. $ pulsar-admin functions restart \
  3.   --tenant public \
  4.   --namespace default \
  5.   --name (the name of Pulsar Functions) \
  6.   --instance-id 1

POST /admin/v3/functions/:tenant/:namespace/:functionName/:instanceId/restart?version=2.10.0

  2. admin.functions().restartFunction(tenant, namespace, functionName, Integer.parseInt(instanceId));

Restart all instances of a function

You can restart all function instances using Admin CLI, REST API or Java admin API.

  • Admin CLI
  • REST API
  • Java Admin API

Use the restart subcommand.

Example

  2. $ pulsar-admin functions restart \
  3.   --tenant public \
  4.   --namespace default \
  5.   --name (the name of Pulsar Functions) \

POST /admin/v3/functions/:tenant/:namespace/:functionName/restart?version=2.10.0

  2. admin.functions().restartFunction(tenant, namespace, functionName);

List all functions

You can list all Pulsar functions running under a specific tenant and namespace using Admin CLI, REST API or Java Admin API.

  • Admin CLI
  • REST API
  • Java Admin API

Use the list subcommand.

Example

  2. $ pulsar-admin functions list \
  3.   --tenant public \
  4.   --namespace default

GET /admin/v3/functions/:tenant/:namespace?version=2.10.0

  2. admin.functions().getFunctions(tenant, namespace);

Delete a function

You can delete a Pulsar function that is running on a Pulsar cluster using Admin CLI, REST API or Java Admin API.

  • Admin CLI
  • REST API
  • Java Admin API

Use the delete subcommand.

Example

  2. $ pulsar-admin functions delete \
  3.   --tenant public \
  4.   --namespace default \
  5.   --name (the name of Pulsar Functions)

DELETE /admin/v3/functions/:tenant/:namespace/:functionName?version=2.10.0

  2. admin.functions().deleteFunction(tenant, namespace, functionName);

Get info about a function

You can get information about a Pulsar function currently running in cluster mode using Admin CLI, REST API or Java Admin API.

  • Admin CLI
  • REST API
  • Java Admin API

Use the get subcommand.

Example

  2. $ pulsar-admin functions get \
  3.   --tenant public \
  4.   --namespace default \
  5.   --name (the name of Pulsar Functions)

GET /admin/v3/functions/:tenant/:namespace/:functionName?version=2.10.0

  2. admin.functions().getFunction(tenant, namespace, functionName);

Get status of an instance of a function

You can get the current status of a Pulsar function instance with instance-id using Admin CLI, REST API or Java Admin API.

  • Admin CLI
  • REST API
  • Java Admin API

Use the status subcommand.

Example

  2. $ pulsar-admin functions status \
  3.   --tenant public \
  4.   --namespace default \
  5.   --name (the name of Pulsar Functions) \
  6.   --instance-id 1

GET /admin/v3/functions/:tenant/:namespace/:functionName/:instanceId/status?version=2.10.0

  2. admin.functions().getFunctionStatus(tenant, namespace, functionName, Integer.parseInt(instanceId));

Get status of all instances of a function

You can get the current status of a Pulsar function instance using Admin CLI, REST API or Java Admin API.

  • Admin CLI
  • REST API
  • Java Admin API

Use the status subcommand.

Example

  2. $ pulsar-admin functions status \
  3.   --tenant public \
  4.   --namespace default \
  5.   --name (the name of Pulsar Functions)

GET /admin/v3/functions/:tenant/:namespace/:functionName/status?version=2.10.0

  2. admin.functions().getFunctionStatus(tenant, namespace, functionName);

Get stats of an instance of a function

You can get the current stats of a Pulsar Function instance with instance-id using Admin CLI, REST API or Java admin API.

  • Admin CLI
  • REST API
  • Java Admin API

Use the stats subcommand.

Example

  2. $ pulsar-admin functions stats \
  3.   --tenant public \
  4.   --namespace default \
  5.   --name (the name of Pulsar Functions) \
  6.   --instance-id 1

GET /admin/v3/functions/:tenant/:namespace/:functionName/:instanceId/stats?version=2.10.0

  2. admin.functions().getFunctionStats(tenant, namespace, functionName, Integer.parseInt(instanceId));

Get stats of all instances of a function

You can get the current stats of a Pulsar function using Admin CLI, REST API or Java admin API.

  • Admin CLI
  • REST API
  • Java Admin API

Use the stats subcommand.

Example

  2. $ pulsar-admin functions stats \
  3.   --tenant public \
  4.   --namespace default \
  5.   --name (the name of Pulsar Functions)

GET /admin/v3/functions/:tenant/:namespace/:functionName/stats?version=2.10.0

  2. admin.functions().getFunctionStats(tenant, namespace, functionName);

Trigger a function

You can trigger a specified Pulsar function with a supplied value using Admin CLI, REST API or Java admin API.

  • Admin CLI
  • REST API
  • Java Admin API

Use the trigger subcommand.

Example

  2. $ pulsar-admin functions trigger \
  3.   --tenant public \
  4.   --namespace default \
  5.   --name (the name of Pulsar Functions) \
  6.   --topic (the name of input topic) \
  7.   --trigger-value \"hello pulsar\"
  8.   # or --trigger-file (the path of trigger file)

POST /admin/v3/functions/:tenant/:namespace/:functionName/trigger?version=2.10.0

  2. admin.functions().triggerFunction(tenant, namespace, functionName, topic, triggerValue, triggerFile);

Put state associated with a function

You can put the state associated with a Pulsar function using Admin CLI, REST API or Java admin API.

  • Admin CLI
  • REST API
  • Java Admin API

Use the putstate subcommand.

Example

  2. $ pulsar-admin functions putstate \
  3.   --tenant public \
  4.   --namespace default \
  5.   --name (the name of Pulsar Functions) \
  6.   --state "{\"key\":\"pulsar\", \"stringValue\":\"hello pulsar\"}"

POST /admin/v3/functions/:tenant/:namespace/:functionName/state/:key?version=2.10.0

  2. TypeReference<FunctionState> typeRef = new TypeReference<FunctionState>() {};
  3. FunctionState stateRepr = ObjectMapperFactory.getThreadLocal().readValue(state, typeRef);
  4. admin.functions().putFunctionState(tenant, namespace, functionName, stateRepr);

Fetch state associated with a function

You can fetch the current state associated with a Pulsar function using Admin CLI, REST API or Java admin API.

  • Admin CLI
  • REST API
  • Java Admin CLI

Use the querystate subcommand.

Example

  2. $ pulsar-admin functions querystate \
  3.   --tenant public \
  4.   --namespace default \
  5.   --name (the name of Pulsar Functions) \
  6.   --key (the key of state)

GET /admin/v3/functions/:tenant/:namespace/:functionName/state/:key?version=2.10.0

  2. admin.functions().getFunctionState(tenant, namespace, functionName, key);